Skip to content

create-fvtt-module

create-fvtt-module is a CLI scaffolding tool that generates a ready-to-ship module structure for Foundry VTT. It walks you through an interactive prompt and writes out a new folder containing everything you need to start developing. A built module.json, source files, build tooling, optional compendium packs, and optional addons.

Quick start

Section titled “Quick start”
Terminal window
npx create-fvtt-module@latest

This prompts you for a title and other configuration, then generates the module in a new folder named after your module ID. Navigate prompts with arrow keys, toggle multiselect options with space, and confirm with enter. When it finishes it prints a cd command to get you started.

To update the globally installed CLI:

Terminal window
npm install -g create-fvtt-module@latest

The CLI checks npm for a newer version on each run and tells you if one is available (using whichever package manager it detects).

What gets generated

Section titled “What gets generated”

Depending on the answers you give, the output can include:

  • A module.json filled in with your title, ID, description, Foundry version compatibility, supported systems, and any pack definitions.
  • Source files with example code (in the vite template).
  • Vite build tooling (in the vite template), including:
    • A dev server that proxies a running Foundry instance, with Hot Module Replacement.
    • FoundryVTT-Sync to build compendium databases from JSON on build.
    • Configurable dev/Foundry ports through a .env file (FOUNDRY_PORT, DEV_PORT).
  • TypeScript support using @7h3laughingman/foundry-types.
  • Compendium packs of the types you select, optionally nested inside a named folder, plus extract and symlink helper scripts.
  • Optional addons (see below).
  • A git repository with an initial commit, if you opt in.

Templates

Section titled “Templates”

When you run the tool you choose a template:

TemplateDescription
viteThe full development setup: Vite, HMR, FoundryVTT-Sync, TypeScript, pack scripts, and example source.
basicA minimal scaffold — essentially just a module.json.

You can preselect one with the --template flag to skip the prompt.

System & version support

Section titled “System & version support”

The tool prompts for a Foundry version (V13 or V14) and lets you select one or more systems (multiselect):

  • dnd5e — Dungeons & Dragons 5th Edition
  • pf2e — Pathfinder 2nd Edition
  • sf2e — Starfinder 2nd Edition

Additional systems and versions can be added in the tool’s src/options.ts.

Compendium packs

Section titled “Compendium packs”

You can scaffold pack definitions for any combination of Adventures, Items, Journals, and Actors. If you select at least one, the tool offers to nest them inside a named folder. The generated vite template includes scripts to manage them:

  • npm run extract — extract compiled packs back into editable JSON (data/).
  • npm run symlink — symlink your build into your Foundry data folder for live development.

Addons

Section titled “Addons”

After the core prompts, you can enable any of these addons (multiselect):

  • Github Workflow — adds GitHub Actions for automated releases.
  • SF2e <=> PF2e UUID Redirects — adds UUID redirects for modules that support both SF2e and PF2e. On by default; automatically skipped unless the module supports both systems.
  • Typed Module API — scaffolds a typed API (types.d.ts, api.ts, and package.json exports) so other modules can consume your types. On by default.

Usage and flags

Section titled “Usage and flags”
Terminal window
create-fvtt-module [title] [options]
FlagDescription
[title]Module title (positional; prompted if omitted).
--auto-idAuto-generate the module ID from the title (skips the ID prompt).
--template <name>Use a specific template (vite or basic).
--migrate-from <path>Migrate compendium packs from an existing module — a local module.json path or a remote URL.
--overrideOverwrite an existing folder without confirmation.
--help, -hShow help.
--version, -vShow the version.

Examples:

Terminal window
create-fvtt-module "My Module" --auto-id
create-fvtt-module --template vite
create-fvtt-module "My Module" --migrate-from ./old-module/module.json
create-fvtt-module "My Module" --migrate-from https://example.com/module.json

Migrating packs from an existing module

Section titled “Migrating packs from an existing module”

--migrate-from reads a module.json (from disk or a URL), extracts its compendium packs, and brings them into your newly scaffolded module. This is useful for splitting content out of an old module or starting a rework without rebuilding your compendiums by hand.

Interactive prompts (reference)

Section titled “Interactive prompts (reference)”

When run without flags, the tool asks (in order, some conditional):

  1. Template — vite or basic.
  2. Module Title — display name.
  3. Module ID — must be lowercase alphanumeric with hyphens (e.g. my-awesome-module); defaults to a slug of the title.
  4. Overwrite? — only if a folder with that ID already exists.
  5. Description.
  6. Foundry Version — V13 or V14.
  7. System(s) — dnd5e / pf2e / sf2e.
  8. Packs — Adventures / Items / Journals / Actors; if any chosen, whether to nest them in a named folder.
  9. Addons — see above.
  10. Install dependencies? — only if the template has a package.json.
  11. Initialize a git repository? — also creates an initial commit.
  12. Run onCreate script? — only if the template ships one.

Further reading

Section titled “Further reading”