Wiki
the map of any codebase

Contributing

Local Setup & Contributing

This guide is derived from the repository's package.json scripts, CI workflow, and TypeScript configuration. There is no CONTRIBUTING.md; the steps below reflect observed tooling only.

Prerequisites

Tested Node.js versions are declared in CI:

  • latest
  • 24
  • 22

CI runs on macos-latest, so local development on macOS most closely matches CI. The test suite uses Playwright, which requires browser binaries.

Install

npm install

After install, the prepare script runs npm run build, which:

  1. Deletes the distribution/ directory via del-cli.
  2. Compiles source/ to distribution/ using tsc --project tsconfig.dist.json.

tsconfig.dist.json sets rootDir: ./source and outDir: ./distribution, extending the base tsconfig.json. The base config sets exactOptionalPropertyTypes: true, so contributions must be compatible with strict optional-property typing.

Note that package-lock.json is git-ignored, so do not commit a lockfile.

Install Playwright Browsers

Several tests (e.g. via test/helpers/with-page.ts, re-exported from test/helpers/index.ts) require browsers. Match CI:

npx playwright install --with-deps

Run the Test Suite

npm test

This runs three stages in order:

  1. xo — lint. Project-specific rule overrides live under the xo key in package.json (e.g. unicorn/filename-case and several @typescript-eslint/no-unsafe-* rules are disabled).
  2. npm run build — type-check and emit to distribution/.
  3. ava — execute tests.

AVA is configured to load TypeScript test files directly via tsx/esm (nodeArguments: ["--import=tsx/esm"]) with the ts extension treated as module. Test files live in test/ (e.g. test/methods.ts, test/stream.ts, test/fetch.ts) and import the library from ../source/index.js.

Debugging Tests

To run AVA with Playwright debug mode and an extended timeout:

npm run debug

This executes PWDEBUG=1 ava --timeout=2m.

Building Only

npm run build

Use this to verify the dist build without running lint or tests. Sourcemaps and inline sources are enabled in tsconfig.dist.json.

Releasing

Releases are performed via np:

npm run release

(Reserved for maintainers.)

Before Opening a PR

At minimum, ensure the full pipeline used by CI passes:

npm install
npx playwright install --with-deps
npm test

CI runs this matrix on Node 22, 24, and latest; code should work on all three.

Cited sources· 6