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:

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.

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

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

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.