FoundryVTT-Sync

2.4.0 verified Sat May 09 auth: no javascript

A cross-bundler plugin version 2.4.0 that syncs FoundryVTT compendiums with the file system, supporting Vite, Rollup, Webpack, and esbuild. It eliminates manual extraction and compilation steps by providing two-way synchronization during development (via WebSocket and HMR, Vite-only) and automatic JSON-to-LevelDB compilation at build time. Unlike alternatives, it does not access the database directly but uses Foundry's own document update mechanisms. Requires Node.js 24 and peer dependencies for each bundler. Ships TypeScript types.

Common errors

error Error: Cannot find module 'foundryvtt-sync' ↓

cause Package not installed or typo in import path.

fix

Run 'npm install --save-dev foundryvtt-sync' and ensure import uses correct subpath (e.g., 'foundryvtt-sync/vite').

error TypeError: foundryvttSync is not a function ↓

cause Default import from 'foundryvtt-sync' returns an array of plugins (Vite), not a function that accepts options.

fix

Use bundler-specific subpath: import foundryvttSync from 'foundryvtt-sync/vite' (for Vite) or import from '/rollup', '/webpack', '/esbuild'.

error Error: foundryvtt-cli is required but not installed ↓

cause Missing peer dependency foundryvtt-cli during build step.

fix

Install foundryvtt-cli as a dev dependency: 'npm install --save-dev foundryvtt-cli'.

Warnings

deprecated Default import from 'foundryvtt-sync' (no subpath) returns Vite plugin array, not bundler-agnostic. This behavior is deprecated and will be removed in v3. ↓

fix Use bundler-specific subpath imports: 'foundryvtt-sync/vite', 'foundryvtt-sync/rollup', etc.

gotcha Dev functionality only supports folders: false and expandAdventures: false in your module.json. Other extraction options will cause misbehavior. ↓

fix Set 'folders: false' and 'expandAdventures: false' in your module.json's pack configuration during development.

gotcha Requires Node.js 24. Older Node versions are not supported and will cause runtime errors. ↓

fix Upgrade Node.js to version 24 or later.

gotcha Webpack users must use require() with the '/webpack' subpath. Importing from default path returns Vite plugin array, not a Webpack plugin. ↓

fix Use const foundryvttSync = require('foundryvtt-sync/webpack') and add to plugins array.

Install

npm install foundryvtt-sync

yarn add foundryvtt-sync

pnpm add foundryvtt-sync

Imports

foundryvttSync
wrong
```
import foundryvttSync from 'foundryvtt-sync'
```
correct
```
import foundryvttSync from 'foundryvtt-sync/vite'
```
Since v2, use bundler-specific subpath: /vite, /rollup, /webpack, /esbuild. Default export is deprecated for cross-bundler use.
foundryvttSync
wrong
```
const foundryvttSync = require('foundryvtt-sync')
```
correct
```
const foundryvttSync = require('foundryvtt-sync/webpack')
```
Webpack uses CommonJS, but import from specific subpath. Default require returns Vite plugin array, not Webpack plugin.
PluginOptions
wrong
```
import { PluginOptions } from 'foundryvtt-sync'
```
correct
```
import type { PluginOptions } from 'foundryvtt-sync'
```
PluginOptions is a TypeScript type, not a runtime value. Use 'import type' to avoid bundling errors.

Quickstart

Shows the recommended Vite setup with options and transformer. Plugin syncs compendiums bidirectionally in dev mode and compiles to LevelDB on build.

// vite.config.ts
import { defineConfig } from 'vite';
import foundryvttSync from 'foundryvtt-sync/vite';
import moduleJSON from './module.json' with { type: 'json' };

export default defineConfig({
  plugins: [
    foundryvttSync(moduleJSON, {
      dataDirectory: 'data',
      outputDirectory: 'packs',
      transformer: async (doc) => {
        doc.system?.customField ? undefined : false;
      }
    }),
  ],
});