Contributing

npm ci and ordinary npm pack prepare the CommonJS, ESM, and declaration files automatically. Git dependency preparation also builds the package, while Husky hooks are installed only for local development in this checkout. Run npm run test:prepare to verify clean-source packaging.

Install and check

npm ci
npm run lint
npm run build
npm test
npm run test:release
npm run smoke
npm run smoke:install
npm run docs
npm run smoke:docs

CI runs on Node.js 22 and 24. Behavior fixes need regression tests. Package changes must pass the packed installation check for CommonJS, native ESM, and TypeScript consumers.

After building, run node scripts/benchmark-verification.js to compare decoding once per verification window with decoding for every candidate. It checks equivalent results and reports timings for ordinary and long Base32 keys; timings are informational and are not CI assertions.

Work on documentation

Edit Markdown in documentation/. Start VitePress with:

npm run docs:serve

npm run docs stages the build in a temporary directory, then replaces the generated docs/ site only after a successful build. Commit the source and generated site together. Preview production output with npm run docs:preview.

For browser verification:

npx playwright install chromium
npm run smoke:docs:browser

The browser check covers navigation, local search, old Docsify links, mobile navigation, and missing assets.

Source layout

Path	Purpose
src/index.ts	OTP generation, verification, encoding helpers, and public types
tests/	RFC vectors, regressions, release checks, and package/docs smoke checks
scripts/	Package and docs builds, version gating, registry verification
documentation/	VitePress source and assets
docs/	Generated GitHub Pages output

Follow the repository's code of conduct when contributing.