Contributing

The full guide lives in CONTRIBUTING.md. This page is the orientation.

Before changing code

Read the architecture page, the relevant ADR, and the package’s README. Most review comments on this repository are about a boundary, not about style — and the boundaries are written down.

Setup

Node.js 22.13 or newer — CI’s full gate runs on 24 — and pnpm 11.17.0.

pnpm install --frozen-lockfile
pnpm exec playwright install chromium firefox webkit

While working

Run the narrow check for what you touched:

pnpm vitest run --project core --project runtime

Then the full gate before opening a pull request:

pnpm check

pnpm check runs, in order: format, lint, root type check, workspace type checks, every Vitest project with coverage thresholds, builds, the dependency-boundary check, package checks (publint and @arethetypeswrong/cli), artifact and archive validation, the documentation build, and Knip.

Anything touching packaging, exports, declarations, or peer dependencies also needs:

pnpm consumers:check

which packs every package and installs the archives into clean projects outside the workspace. It needs network access and takes about two minutes.

Do not weaken a gate to pass

If a rule is genuinely wrong for a case, disable it at the narrowest possible scope with a comment explaining why, and say so in the pull request. Muting a check to make a change pass is the one thing this repository treats as a hard error.

The rules a change has to respect

1. Keep the dependency graph directional. A package may depend only on what scripts/packages.mjs allows it to.

2. Keep core framework-independent. No framework dependency in @queryweave/core, ever, and no React dependency anywhere.

3. Respect the globals boundary. No browser global in core, server, node, vue, or nuxt — the checker matches whole words in source text, comments included. No Node built-in in core or server.

4. Use public entry points. Never import another package’s source path.

5. Keep the layers honest. An adapter must not decode, validate, or apply defaults. A codec must not navigate, read a request, touch globals, or create reactive state.

6. Do not add a rejected identity. useQueryState, useQueryStates, parseAs*, createParser, createLoader, createSerializer, withDefault, and tuple setters are rejected by ADR 0001 and by a test.

7. Write an ADR for a cross-package architectural decision or any breaking public API change.

8. Add a changeset for anything a consumer can observe.

   pnpm changeset

   Versioning and npm publish are described in Releasing.

Adding a parameter family or an adapter

Both have a shape worth following:

• A new parameter family needs both directions, an issue for every failure mode, round-trip tests, type tests, and a documentation page.
• A new adapter needs the four contract methods, lazy subscription, deterministic cleanup, and tests against the memory adapter’s behavior. See writing an adapter.

Documentation

This site lives in apps/docs and is built with Astro and Starlight. Two rules matter more than the rest:

• Never document an API that does not exist. Planned work belongs on the roadmap, marked as planned.
• Do not make Vue or Nuxt the identity. They are integrations. Core pages stay framework-independent.

Run it locally:

pnpm docs:dev

Reporting a security issue

Do not open a public issue. Follow SECURITY.md.