Local Setup and Workflow

Local Setup and Workflow

TLDR

• packs/_source/ is editable content; packs/ is generated output
• LESS changes need npm run build:styles
• compendium changes need Foundry stopped, then npm run build:db, then a Foundry restart
• code, template, localization, and built CSS changes usually need only a browser reload

This guide is for working on the sw5e-module repository in a practical local setup.

It focuses on:

• where the module lives in Foundry
• which folders are safe to edit
• when you need a browser reload, a style rebuild, or a pack rebuild
• which commands you will use most often
• what to check if a change does not show up

For broader project structure and contributor expectations, use:

• Developer Guide
• Developer Reference
• Testing & Contribution

What this repo targets

Unless a task says otherwise, assume this repo is being worked on with:

• Foundry VTT v13.x
• DND5e v5.2.5
• lib-wrapper enabled in the test world

Where the module usually lives

Foundry loads modules from its Data/modules/ folder.

On Windows, many contributors use a junction or symlink so the Git repository can stay in a normal working folder while still appearing to Foundry as:

Data/modules/sw5e-module

The important rule is that the Foundry-side module directory must be named sw5e-module.

Safe places to edit

These folders are normal places to make changes:

• packs/_source/ for compendium source data
• scripts/ for module behavior and compatibility patches
• applications/ for custom application code
• templates/ for sheet or UI templates
• styles/ for LESS and CSS styling
• languages/ for localization text
• icons/ for images and assets
• README.md and docs/ for documentation

Do not edit these by hand

• packs/ because it is generated output
• node_modules/ because it is installed automatically

The most important source-of-truth rule is:

• edit packs/_source/
• build into packs/

Commands you will use most often

• npm run lint
• npm run build:styles
• npm run build:db
• npm run build:json
• npm run build:clean

What each one is for

npm run lint
Checks the repo’s current lint or type expectations.

npm run build:styles
Builds the LESS sources into the shipped CSS output.

npm run build:db
Builds the editable compendium JSON in packs/_source/ into Foundry-ready compendium data in packs/.

npm run build:json
Extracts built compendium data back into JSON source files.

npm run build:clean
Cleans and normalizes compendium source data.

Very important pack-build note

npm run build:db requires Foundry to be fully stopped.

This is one of the most important workflow rules in the project, because Foundry can hold a LevelDB lock on packs/ while it is running.

What kind of reload you need

This is one of the most useful practical distinctions in the whole workflow.

If you changed scripts, templates, localization, or built CSS

Use:

• a browser reload of Foundry

This is the common path for:

• scripts/
• templates/
• languages/
• styles/module.css

If you changed LESS

Use:

1. npm run build:styles
2. then a browser reload of Foundry

Changing LESS alone is not enough, because Foundry reads the built CSS, not the raw LESS source.

If you changed packs/_source

Use:

1. fully stop Foundry
2. run npm run build:db
3. restart Foundry

For pack changes, a normal browser reload is not enough.

Normal workflow

If you change compendium content

1. edit the relevant file in packs/_source/
2. fully stop Foundry
3. run npm run build:db
4. restart Foundry
5. open the affected compendium entry and confirm the change appears

If you change code, templates, localization, or built CSS

1. edit the relevant file
2. if you changed LESS, run npm run build:styles
3. browser-reload Foundry
4. test the feature that changed

Quick testing assumptions

Unless a task says otherwise, a good default test setup is:

• Foundry VTT 13
• dnd5e 5.2.5
• lib-wrapper installed and enabled
• a normal test world using the standard dnd5e sheets

If you also use other sheet or UI modules, mention that when reporting problems because they can change how the module behaves.

Recommended quick checks

After changes, the most useful things to verify are:

• the module loads without startup errors
• actors and items open normally
• powers and maneuvers appear in the expected sheet areas
• compendium entries open and import correctly
• any edited item, class, feat, species, or monster shows the expected data in Foundry

For broader testing expectations and contribution discipline, use Testing & Contribution.

Troubleshooting

I edited something but nothing changed in Foundry
Check whether you changed:

• packs/_source/, which needs npm run build:db and a Foundry restart
• LESS, which needs npm run build:styles before a browser reload
• ordinary code or templates, which usually need only a browser reload

Foundry is open and build:db failed
Close Foundry fully and run the build again.

I am not sure which file to edit
Use this shortcut:

• compendium entry change -> packs/_source/
• sheet behavior change -> scripts/ or applications/
• visible layout change -> templates/ or styles/
• wording or labels -> languages/

For a broader “where does this kind of change usually live?” map, use Developer Reference.

What to include when requesting help

When asking for help with this repo, include:

• what you were trying to change
• the compendium entry, actor, item, or feature involved
• what you expected to happen
• what actually happened
• whether you already ran the needed build or reload step
• whether the problem happens in a plain dnd5e world with only lib-wrapper and this module enabled