Contributing

Contributing

The toolkit is GPL and built to be extended. The canonical contributor docs live in the repo and travel with the code:

• CONTRIBUTING.md - setup, tests, the rules that get PRs merged, the PR flow.
• docs/webviews.md - how the visual tools (GUI editor, event graph, Flag Builder, Workshop panel, Examples Wiki) are built, and the checklist for adding a new one.
• AGENTS.md - the full architecture and conventions reference.

This page is the short version, with the development loops spelled out.

What helps most

Concrete examples from real mods: a script snippet the toolkit handles wrongly, with the file it came from. Wrong or missing folder mappings (especially EU5) have their own Schema gap issue form, and the per-game schema tables (packages/server/src/games/<game>/schema.ts) are deliberately small and community-editable, so fixing one is a good first PR.

Wiki contributions

Useful guides, tips, tools and examples are welcome too. Contact me to suggest a wiki addition if you think it would help the community. No code contribution is needed.

Setup

You need Node 22 or newer and pnpm. A game install is not required for most work.

git clone https://github.com/JDeffner/paradox-modding-toolkit.git
cd paradox-modding-toolkit
pnpm install
pnpm run compile

The three development loops

Pick by what you are iterating on, fastest first.

1. Browser preview, for UI work

pnpm run preview:webviews
pnpm run preview:webviews -- path/to/some_window.gui

This starts a dev server on http://localhost:5317 with two pages:

• /gallery renders every px-ui component (buttons, menus, dialogs, toasts, color picker, sortable lists) from the live stylesheet. Edit anything under packages/vscode/src/webviews/shared/ and the page reloads on save.
• /gui boots the real GUI editor over a stub host, laying out the .gui file you passed. Nothing is written to disk.

Buttons at the bottom right switch between a Dark and a Light stand-in for the VS Code theme. You get real browser devtools here, which webviews inside VS Code never give you.

2. Live panels, for feature work

Use the separate PXTK Development profile for toolkit checks. F5 and package:test select it. Before the first test installation, create the profile by launching it:

code --new-window --profile "PXTK Development"

For Live Webview, install the companion into that profile:

code --profile "PXTK Development" --install-extension JDeffner.live-webview

The companion must be enabled in the Extension Development Host. The current development build also needs the built helper from a Live Webview checkout: run pnpm build there and set liveWebviewPath in the toolkit's ignored dev-paths.json, or PX_LIVE_WEBVIEW_PATH, to that checkout. Installing the Marketplace companion alone does not supply the helper.

Select Run Extension + Live Webview and press F5. It builds the development version and starts pnpm run watch:webviews:live. Successful frontend builds reload the affected panels; failed builds keep the current panel. Use the companion's Explorer view to pause, resume or reload an instance, and its logs to inspect callbacks.

Host code, HTML generators and their imported CSS require a rebuild and host restart. Reload restores state that the panel saves or requests from its host; unsaved DOM state can be lost. The normal watch:webviews loop and Run Extension remain available. See the canonical webview guide for the full setup.

3. The packaged artifact

pnpm run package:test

This compiles, packages and installs the test VSIX into PXTK Development. Reload that window and exercise the affected action through its real entry point. Check the visible or saved result and a relevant failure case. Installation alone is not an editor check. Normal packaging removes the Live Webview helper.

Automated extension-host suites should use disposable user-data and extensions folders under .local/testing/, with the same isolation arguments for installation and launch. Keep generated mods and test outputs in ignored local folders. Never commit a VSIX.

Verify before you push

pnpm run typecheck
pnpm run lint
pnpm test

Some test suites need paths to a game install or a mod corpus, read from a gitignored dev-paths.json (copy dev-paths.example.json). Without it they skip, loudly, and that is fine. If you touched packages/server/src, also run node scripts/check-game-boundary.mjs.

Sending a PR

Branch from main (feat/, fix/, docs/, chore/), add one changelog bullet under "Unreleased" in packages/vscode/CHANGELOG.md, and open the PR. CI and an automated review run on every PR; the maintainer squash-merges. The full rules, including the ones that will get a PR bounced (hand-written game knowledge, vscode imports in the server, per-game if checks), are in CONTRIBUTING.md.