nuqs Agent Rules

Type-safe URL query state for React applications.

Overview

nuqs states a few URL-state rules, then points each task to a detailed contributor guide. It also names the task-runner entry points, shows how to enable browser and server debug logs, and defines when a change is done.

Documents

├── 
├── .agents
│   └── docs
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       ├── 
│       └── 
├── packages
│   └── docs
│       └── 
├── 
└──

Patterns in this file

Router files

01 / Router files

Route common tasks to the relevant guide

A table maps bugs, parsers, adapters, performance, documentation, and pull requests to focused documents. It gives an entry path into the material without loading every guide for every change.

62| Task                    | Guide                                                                             |63| ----------------------- | --------------------------------------------------------------------------------- |64| Fix a bug               | See [Testing Patterns](.agents/docs/testing.md) → Regression                      |65| Add a new parser        | See [Parser Implementation](.agents/docs/parser-implementation.md)                |66| Add a framework adapter | See [Adapter Development](.agents/docs/adapter-development.md)                    |67| Improve performance     | See [API Design](.agents/docs/api-design.md) → Performance & Reliability          |68| Update documentation    | See [Release & Git Workflow](.agents/docs/git-workflow.md) → Documentation        |69| Prepare a pull request  | See [Release & Git Workflow](.agents/docs/git-workflow.md) → PR Quality Checklist |

Preserve the task graph when filtering tests

Focused tests must use root Turbo commands instead of invoking package scripts directly. The file also documents the full suite’s duration and included build, unit, typing, and end-to-end stages.

41- **Test suite:** `pnpm test` (5-10 minutes; includes build + unit + typing + e2e)42- **Focused tests:** Use the root Turbo command, for example `pnpm run test --filter nuqs` or `pnpm run test --filter e2e-next`. Do not invoke package test scripts directly.

Record URL-state invariants together

The core concepts define lossless pure serialization, internal defaults, and null on invalid parsing. These rules establish observable behavior for parser and state changes.

30- **Key Principles:**31  1. URL = single source of truth32  2. Serialization must be lossless & pure33  3. Defaults are internal (not written to URL)34  4. Invalid parse → return `null`

Make debug collection part of reproduction

The guide gives browser and server activation steps for the opt-in debug bundle. It then asks for debug logs in issue reports and reproduction scripts.

75Import the opt-in debug bundle once in each runtime where logs are needed:76 77```ts78import 'nuqs/debug'79```80 81Then enable debug logs in the browser console and reload the page:82 83```js84localStorage.setItem('debug', 'nuqs')85```86 87In server or Node environments (e.g. when using `nuqs/server`), set the `DEBUG` environment variable so it contains `nuqs`:88 89```bash90DEBUG=nuqs pnpm dev91```92 93Hook-level logs are prefixed with `[nuq+ …]`; internal subsystems use `[nuqs <subsystem>]` (see `packages/nuqs/src/lib/debug-messages.ts` for the catalog).94 95Encourage debug logs in issue reports and include them in reproduction scripts.

Ideas for your repo

Map frequent tasks directly to their deeper guides.
Document the task-runner entry point required for focused tests.
Write state and serialization invariants as observable behavior.
Include opt-in diagnostics in reproduction instructions.