vite-plugin-foundryvtt/README.md

Plugin for building for foundryvtt. Enables hmr and manifest substitution.

# Vite Plugin FoundryVTT

Bridges the gap between foundry and vite by setting up vite's hotUpdate to
work with foundry's hotReload, build configured compendium packs and rewrite
the manifest with basic substitutions.  It's primarily configured using the
foundry system.json or module.json file.

## Usage

Example `vite.config.mts`:
```typescript
import { defineConfig } from "vite";
import foundryvtt from "vite-plugin-foundryvtt";

import systemJson from "./src/system.json";
const substitutions = {
  // Substitute values with environment variables set in CI
  download: process.env.ARCHIVE_URL,
  manifest: process.env.MANIFEST_URL,
};

export default defineConfig({
  base: "/systems/mysystem/",
  server: {
    port: 30001,
    open: "/",
    proxy: {
      "^(?!/systems/mysystem/)": "http://localhost:30000/",
      "/socket.io": {
        target: "ws://localhost:30000",
        ws: true,
      },
    },
  },
  build: {
    emptyOutDir: false, // Recommended for watch mode and rebuilds with foundry running
    sourcemap: true,
    lib: { name: "mysystem", entry: "src/mysystem.mjs", formats: ["es"], fileName: "mysystem" },
  },
  esbuild: { keepNames: true },
  // Configure foundryvtt stuff
  plugins: [foundryvtt(systemJson, { substitutions })],
});
```

The optional second parameter is an object of options for plugin specific
things.  All values are optional.

```typescript
export interface FoundryVTTPluginConfig {
	/**
	 * Top-level keys to replace in the manifest data. A shallow merge is used.
	 * Intended for replacing manifest and download links in ci builds.
	 * @default `{}`
	 */
	substitutions?: Record<string, unknown>;
	/**
	 * Package type
	 * @default `"system"`
	 */
	type?: "system" | "module";
	/**
	 * Source directory for pack files
	 * @default `"src/packs"`
	 */
	packDir?: string;
	/**
	 * Whether to attempt to build configured compendium packs
	 * @default `true`
	 */
	buildPacks?: boolean;
	/**
	 * Options passed through to the pack compile operation
	 * @default `{ yaml: true }`
	 */
	packOptions?: CompileOptions;
}
```

### Compendium Packs

Configuration for building the packs is read from the package manifest.  The
default source directory for packs is `src/packs` but can be changed with the
packDir option in the plugin config.  The compilePack invocation can be
customized using the `packOptions` parameter, which is passed directly as the
options parameter in the call.  See the foundryvtt-cli docs for more info.
[compilePack documentation](https://github.com/foundryvtt/foundryvtt-cli?tab=readme-ov-file#compilepacksrc-string-dest-string-options-object-promisevoid)

The plugin will attempt to detect if the compendium packs are in use and skip
building them if it detects that they are locked.  It is recommended to
disable `build.emptyOutDir` for builds performed with foundry running since it
has poor interaction with foundry when building packs.  Foundry locks the
database files when in use, but emptyOutDir will delete them.  This prevents
the plugin from detecting that the databases are in use and leads to packs
being empty.

Compendium pack building can be turned off entirely by setting `buildPacks` to
false in the plugin options.

### Hot Reload

Hot Reload config is read from the foundry package manifest.  When editing a
file matching the config in `publicDir`, automatically copy that file to the
output to trigger the foundry hotReload mechanism.  It's generally unnecessary
to set up hotReload for css with vite since vite handles css hot updating
already.

[More Info](https://github.com/foundryvtt/foundryvtt/issues/9027)

### Manifest Output

The manifest is written to `outDir` with optional substitutions provided by
the `substitutions` option.  Substitution values are merged in using vite's
mergeConfig function.  More advanced transformations of the manifest data can
be done via javascript if desired.  The filename of the written manifest is
based on the configured foundry package type which is configured by the `type`
plugin option, one of either `"system"` or `"module"`.  The default value is
`"system"` and `"world"` foundry packages are unsupported.

### Style output

When writing the css file output, it will be redirected to a styles directory
in the outDir (`dist` by default) in order to work around a bug in vite.