{"id":27754,"library":"foundryvtt-sync","title":"FoundryVTT-Sync","description":"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.","status":"active","version":"2.4.0","language":"javascript","source_language":"en","source_url":"https://github.com/MrVauxs/FoundryVTT-Sync","tags":["javascript","typescript"],"install":[{"cmd":"npm install foundryvtt-sync","lang":"bash","label":"npm"},{"cmd":"yarn add foundryvtt-sync","lang":"bash","label":"yarn"},{"cmd":"pnpm add foundryvtt-sync","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used at build time to compile JSON files into LevelDB database directories.","package":"foundryvtt-cli","optional":false}],"imports":[{"note":"Since v2, use bundler-specific subpath: /vite, /rollup, /webpack, /esbuild. Default export is deprecated for cross-bundler use.","wrong":"import foundryvttSync from 'foundryvtt-sync'","symbol":"foundryvttSync","correct":"import foundryvttSync from 'foundryvtt-sync/vite'"},{"note":"Webpack uses CommonJS, but import from specific subpath. Default require returns Vite plugin array, not Webpack plugin.","wrong":"const foundryvttSync = require('foundryvtt-sync')","symbol":"foundryvttSync","correct":"const foundryvttSync = require('foundryvtt-sync/webpack')"},{"note":"PluginOptions is a TypeScript type, not a runtime value. Use 'import type' to avoid bundling errors.","wrong":"import { PluginOptions } from 'foundryvtt-sync'","symbol":"PluginOptions","correct":"import type { PluginOptions } from 'foundryvtt-sync'"}],"quickstart":{"code":"// vite.config.ts\nimport { defineConfig } from 'vite';\nimport foundryvttSync from 'foundryvtt-sync/vite';\nimport moduleJSON from './module.json' with { type: 'json' };\n\nexport default defineConfig({\n  plugins: [\n    foundryvttSync(moduleJSON, {\n      dataDirectory: 'data',\n      outputDirectory: 'packs',\n      transformer: async (doc) => {\n        doc.system?.customField ? undefined : false;\n      }\n    }),\n  ],\n});","lang":"typescript","description":"Shows the recommended Vite setup with options and transformer. Plugin syncs compendiums bidirectionally in dev mode and compiles to LevelDB on build."},"warnings":[{"fix":"Use bundler-specific subpath imports: 'foundryvtt-sync/vite', 'foundryvtt-sync/rollup', etc.","message":"Default import from 'foundryvtt-sync' (no subpath) returns Vite plugin array, not bundler-agnostic. This behavior is deprecated and will be removed in v3.","severity":"deprecated","affected_versions":">=2.0.0 <3.0.0"},{"fix":"Set 'folders: false' and 'expandAdventures: false' in your module.json's pack configuration during development.","message":"Dev functionality only supports folders: false and expandAdventures: false in your module.json. Other extraction options will cause misbehavior.","severity":"gotcha","affected_versions":">=2.0.0"},{"fix":"Upgrade Node.js to version 24 or later.","message":"Requires Node.js 24. Older Node versions are not supported and will cause runtime errors.","severity":"gotcha","affected_versions":">=2.4.0"},{"fix":"Use const foundryvttSync = require('foundryvtt-sync/webpack') and add to plugins array.","message":"Webpack users must use require() with the '/webpack' subpath. Importing from default path returns Vite plugin array, not a Webpack plugin.","severity":"gotcha","affected_versions":">=2.0.0"}],"env_vars":null,"last_verified":"2026-05-09T00:00:00.000Z","next_check":"2026-08-07T00:00:00.000Z","problems":[{"fix":"Run 'npm install --save-dev foundryvtt-sync' and ensure import uses correct subpath (e.g., 'foundryvtt-sync/vite').","cause":"Package not installed or typo in import path.","error":"Error: Cannot find module 'foundryvtt-sync'"},{"fix":"Use bundler-specific subpath: import foundryvttSync from 'foundryvtt-sync/vite' (for Vite) or import from '/rollup', '/webpack', '/esbuild'.","cause":"Default import from 'foundryvtt-sync' returns an array of plugins (Vite), not a function that accepts options.","error":"TypeError: foundryvttSync is not a function"},{"fix":"Install foundryvtt-cli as a dev dependency: 'npm install --save-dev foundryvtt-cli'.","cause":"Missing peer dependency foundryvtt-cli during build step.","error":"Error: foundryvtt-cli is required but not installed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}