Skip to content

Development ​

Requirements ​

  • Node.js ≥ 20 and npm
  • just (command runner)
  • Chromium for end-to-end tests (Playwright)
  • bun only for the QRShare integration tests
  • uv for uvx reuse lint (licensing check)

Commands ​

CommandDescription
just installInstall dependencies (npm ci)
just devStart the development server
just testRun the unit tests (Vitest + jsdom)
just typecheckType-check with tsc --noEmit (strict mode)
just buildProduction build into dist/ (with service worker)
just previewServe the production build
just e2eEnd-to-end smoke tests (Playwright)
just e2e-qrshareIntegration tests with a real QRShare build (requires bun)
just docsBuild this documentation, plus llms.txt and llms-full.txt
just docs-devLive-preview this documentation
just reuseCheck that every file has its copyright and licence (REUSE: REUSE.toml, LICENSES/)
just checkEverything a contributor must run before committing

Workflow ​

  • Requirements are written with EARS (Easy Approach to Requirements Syntax) and prioritised with MoSCoW. Tests reference requirement IDs in their describe() titles (for example DOC-001).
  • Test-driven development: write the failing test first, then the code.
  • Commits follow Conventional Commits.
  • The project follows Semantic Versioning: roadmap phases were 0.0.x milestones up to 0.0.13, then 0.1.0 (see ROADMAP.md); new features bump the minor version while in 0.x.
  • Every notable change is listed in CHANGELOG.md (Keep a Changelog).
  • AI assistance is disclosed with an Assisted-by: AI commit trailer.

Translations ​

User-visible strings live in src/i18n/en.ts (reference), fr.ts and zh.ts, and are looked up with t('key', { param }). The French and Chinese catalogs are typed as Record<MessageKey, string>, so a missing key fails the type-check, and tests/i18n.test.ts also checks that placeholders match. To add a language: create a catalog, register it in src/i18n/index.ts (LOCALES, CATALOGS, detectLocale).