Building and Testing¶

Prerequisites¶

Node.js ≥ 24
npm (comes with Node.js)

Install dependencies¶

npm install

Build scripts¶

npm run build          # Build for both Chrome and Firefox
npm run build:chrome   # Build only the Chromium extension
npm run build:firefox  # Build only the Firefox extension
npm run build:watch    # Automatically rebuild on file changes

Build output goes to build/chrome/ and build/firefox/.

Environment variables¶

Variable	Values	Default	Notes
`BUILD_TYPE`	`dev`, `beta`, `stable`	`dev`	Use `dev` for local builds. Beta/stable are for distribution.
`BUILD_TARGET`	`all`, `chrome`, `firefox`	`all`	Use `chrome` or `firefox` for faster intermediate builds.
`BUILD_SHA`	any commit hash	—	Required for beta/stable. Leave unset for dev builds.

Loading in a browser¶

Chromium (Chrome, Edge, Brave, etc.)¶

Go to chrome://extensions (or edge://extensions, etc.).
Enable “Developer mode”.
Click “Load unpacked extension…”.
Select the build/chrome directory.

Firefox¶

Go to about:debugging.
Click “This Firefox” in the sidebar.
Click “Load Temporary Add-on…”.
Select build/firefox/manifest.json.

Tests and static analysis¶

npm test             # Run unit tests (Vitest)
npm run test:watch   # Run tests in watch mode
npm run typecheck    # TypeScript type-check (no emit)
npm run lint         # ESLint, then lint:guard
npm run lint:guard   # Moderation-import and listing-envelope guards (also run by lint)
npm run lint:css     # Stylelint
npm run lint:params  # Parameter-order convention check
npm run fmt          # Formatting check (dprint)
npm run fmt:fix      # Auto-fix formatting

Pre-commit checklist¶

CI (.github/workflows/main.yml) runs these checks in this order on Node 24. Run them locally before committing; all must pass cleanly.

npm run fmt             # Formatting check (dprint)
npm run lint            # ESLint + lint:guard
npm run lint:css        # Stylelint
npm run lint:params     # Parameter-order and naming conventions
npm run typecheck       # TypeScript type-check (no emit)
npm test                # Unit tests (Vitest)
npm run build           # Full production build (Chrome + Firefox)

When fmt, lint, or lint:css fail, the auto-fix variants resolve most issues; re-run the checks afterwards:

npm run fmt:fix         # Auto-fix formatting with dprint
npm run lint:fix        # Auto-fix ESLint issues
npm run lint:css:fix    # Auto-fix CSS style issues with Stylelint

Documentation¶

npm run docs:api     # Generate TypeDoc Markdown → docs/developer/api/

After running npm run docs:api, build Sphinx to include the generated API reference:

pip install -r docs/requirements.txt
make -C docs html