Registry / devops / foundryvtt-sync

foundryvtt-sync

library2.4.0jsnpmunverified

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.

devops data serialization

npm install foundryvtt-sync

github ↗package ↗

INSTALL

IMPORT

SIG · FOUNDRYVTT-SYNC

foundryvtt-sync

devopsjavascriptv2.4.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

foundryvttSync

✓ import foundryvttSync from 'foundryvtt-sync/vite'

✗ import foundryvttSync from 'foundryvtt-sync'

Since v2, use bundler-specific subpath: /vite, /rollup, /webpack, /esbuild. Default export is deprecated for cross-bundler use.

foundryvttSync

✓ const foundryvttSync = require('foundryvtt-sync/webpack')

✗ const foundryvttSync = require('foundryvtt-sync')

Webpack uses CommonJS, but import from specific subpath. Default require returns Vite plugin array, not Webpack plugin.

PluginOptions

✓ import type { PluginOptions } from 'foundryvtt-sync'

✗ import { PluginOptions } from 'foundryvtt-sync'

PluginOptions is a TypeScript type, not a runtime value. Use 'import type' to avoid bundling errors.

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; } }), ], });

Debug

Known issues

deprecatedDefault 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.

affects: >=2.0.0 <3.0.0

gotchaDev 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.

affects: >=2.0.0

gotchaRequires Node.js 24. Older Node versions are not supported and will cause runtime errors.

fix

Upgrade Node.js to version 24 or later.

affects: >=2.4.0

gotchaWebpack 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.

affects: >=2.0.0

Errors

Common errors & fixes

Error: Cannot find module 'foundryvtt-sync'

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').

TypeError: foundryvttSync is not a function

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: foundryvtt-cli is required but not installed

Missing peer dependency foundryvtt-cli during build step.

fix

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

Upgrade

Version history

2.4.0latest on npm

Audit

Dependencies

foundryvtt-clirequiredUsed at build time to compile JSON files into LevelDB database directories.

Agent activity

5 hits · last 30 days

node

Resources

githubhttps://github.com/MrVauxs/FoundryVTT-Sync ↗

packagehttps://www.npmjs.com/package/foundryvtt-sync ↗