Use nuqs

Quick Start

1. Confirm the task is in a React 19+ and TypeScript 5.9+ codebase.
2. If Next.js is involved, assume Next.js 16+, stay in App Router only, and keep

   page.tsx

   /

   layout.tsx

   server-first unless client behavior is required.
3. Assume supported browsers are Chrome 146+, Firefox 148+, and Safari 26+.
4. Reuse existing parser descriptors or custom hooks before adding new query keys.
5. Choose a typed parser, URL encoding format, and default value before wiring UI state.
6. Use

   useQueryStates

   when related params must update atomically.
7. For controlled inputs, never pass

   null

   as

   value

   ; use

   withDefault('')

   or

   value={query ?? ''}

   when binding nuqs state directly.
8. Enable server re-renders only when the feature genuinely depends on server-side data or RSC updates.
9. Load only the reference files needed for the task.

Scope Guards

• Support React 19+ only.
• Support TypeScript 5.9+ only.
• Support Next.js 16+ App Router only when Next.js is present.
• Support evergreen browsers Chrome 146+, Firefox 148+, and Safari 26+ only.
• Exclude Next.js Pages Router, Remix, React Router, TanStack Router, and JavaScript-only variants unless explicitly documenting them as out of scope.
• Treat upstream references to Pages Router or non-Next adapters as inventory only, not implementation guidance for this skill.
• Do not add legacy browser compatibility workarounds unless explicitly requested.

Reference Routing

• Load references/parser-and-setup.md for adapter setup, parser selection, defaults, shared descriptors, and custom parser rules.
• Load references/state-and-server-integration.md for

  useQueryState

  ,

  useQueryStates

  , loaders, caches, Suspense, and App Router server integration.
• Load references/performance-navigation-and-limits.md for history behavior, rate limiting, URL hygiene, shorter keys, and browser limits.
• Load references/debugging-testing-and-troubleshooting.md for debug logs, testing adapters, parser tests, and common failure modes.
• Load references/source-basis.md for canonical source provenance.

Workflow

1. Scope the query-state contract.

• Identify which state belongs in the URL because it must survive refresh, deep links, shareable URLs, or browser navigation.
• Keep secrets, oversized payloads, and purely ephemeral state out of the URL.

1. Define the parser layer first.

• Centralize key names, parsers, defaults, and shared options in a dedicated module.
• Prefer built-in parsers over ad hoc string coercion.
• Choose array and date encodings deliberately instead of letting each caller invent one.
• Add schema validation after parsing when domain constraints matter.

1. Wire client state deliberately.

• Use

  useQueryState

  for a single key.
• Use

  useQueryStates

  for coordinated params, partial updates, or atomic commits.
• Clear keys with

  null

  .
• Use functional updates when deriving from previous state.

1. Integrate App Router server behavior only when needed.

• Import loaders, caches, and shared parsers from

  nuqs/server

  .
• Parse

  searchParams

  before reading cached values in server components.
• Use

  shallow: false

  only when the URL update must trigger server work.
• Pair server-triggered updates with Suspense and

  startTransition

  when loading state matters.
• Do not assume

  startTransition

  implies

  shallow: false

  ; configure both when server work is required.

1. Optimize URL update behavior.

• Use

  history: 'replace'

  for ephemeral filters and high-frequency edits.
• Use

  history: 'push'

  for navigation-like state that should replay with back/forward.
• Debounce search-like inputs and throttle rapid updates when browser limits or server churn matter.
• Keep nuqs hooks in the smallest practical subtree and memoize expensive siblings that do not depend on query state.
• Keep URLs short and stable with defaults,

  urlKeys

  , and serializer utilities when needed.
• Do not add compatibility branches for unsupported legacy browsers or older React/Next.js releases.

1. Validate the behavior end to end.

# run project-specific equivalents as available
pnpm -s tsc --noEmit
pnpm -s lint
pnpm -s test

pnpm -s test -- --runInBand        # isolate flaky URL/state tests
pnpm -s test searchParams          # focused component or hook tests
pnpm -s test:e2e                   # back/forward, refresh, and deep-link verification

Non-Negotiable Rules

• Use

  useQueryState

  and

  useQueryStates

  only in React client components.
• Wrap the app with

  NuqsAdapter

  when using Next.js App Router.
• Import server-safe parsers, loaders, and caches from

  nuqs/server

  .
• Do not use different parsers for the same query key across components.
• Do not keep non-string query data as raw strings when a typed parser exists.
• Do not assume nuqs parsers validate business rules or object shape.
• Do not default to

  shallow: false

  ; use it only for intentional server re-renders.
• Do not put sensitive, bulky, or non-shareable state in the URL.
• Do not skip

  eq

  on custom non-primitive parsers.
• Prefer shared parser descriptors or custom hooks over repeating inline parser setup.

Output Expectations

1. State the parser and key contract being introduced or reused.
2. Call out whether the change is client-only or App Router client/server coordinated.
3. Mention history, shallow/server-render, and rate-limiting decisions when they affect behavior.
4. Include tests or manual verification notes for refresh, deep-link, and back/forward behavior.
5. State assumptions about React, TypeScript, and whether Next.js App Router is present.