Use nuqs

Keep URL-backed state predictable, typed, shareable, and aligned between React clients and Next.js App Router server code. Never add legacy browser or older framework compatibility workarounds.

Baseline

• React 19+, TypeScript 5.9+, evergreen browsers Chrome 146+/Firefox 148+/Safari 26+.
• Next.js 16+ App Router only when Next.js is present.
• No Pages Router, no Remix/React Router/TanStack Router, no legacy browser shims.

Reference Routing

Load only what the task needs:

• references/parser-and-setup.md — adapter setup, parser selection, defaults, shared descriptors, custom parsers.
• references/state-and-server-integration.md — useQueryState, useQueryStates, loaders, caches, Suspense, App Router server integration.
• references/performance-navigation-and-limits.md — history behavior, rate limiting, URL hygiene, browser limits.
• references/debugging-testing-and-troubleshooting.md — debug logs, testing adapters, parser tests, failure modes.
• references/source-basis.md — canonical source provenance.