nuqs

name	nuqs
description	Type-safe URL query state management with nuqs 2.x. Use when writing or reviewing code that uses useQueryState, useQueryStates, URL search params, query parameters, nuqs parsers, createLoader, createSearchParamsCache, createSerializer, or URL state in Next.js, React, Remix, React Router, or TanStack Router.

nuqs Best Practices

Type-safe URL query state management with nuqs 2.x. Contains rules across 8 categories, prioritized by impact.

Rule Categories

Priority	Category	Impact	Prefix
1	Parser Configuration	CRITICAL	parser-
2	Adapter & Setup	CRITICAL	setup-
3	State Management	HIGH	state-
4	Server Integration	HIGH	server-
5	Performance	MEDIUM	perf-
6	History & Navigation	MEDIUM	history-
7	Debugging & Testing	LOW-MEDIUM	debug-
8	Advanced Patterns	LOW	advanced-

Quick Reference

1. Parser Configuration (CRITICAL)

• parser-typed — Use typed parsers for non-string values
• parser-with-default — Use withDefault for non-nullable state
• parser-enum-literals — Use literal/enum parsers for constrained values
• parser-array-format — Choose correct array parser format
• parser-json-validation — Validate JSON parser with Standard Schema
• parser-date-format — Select appropriate date parser
• parser-index-offset — Use parseAsIndex for 1-based URL display
• parser-hex-colors — Use parseAsHex for color values
• parser-custom — Create custom parsers for complex types

2. Adapter & Setup (CRITICAL)

• setup-adapter — Wrap app with correct NuqsAdapter
• setup-client-hooks — Add 'use client' for hooks
• setup-server-imports — Import server utilities from nuqs/server
• setup-shared-parsers — Define shared parsers in a dedicated file

3. State Management (HIGH)

• state-use-query-states — Use useQueryStates for related parameters
• state-functional-updates — Use functional updates for derived state
• state-clear-with-null — Clear URL parameters with null
• state-controlled-inputs — Handle controlled input value properly
• state-avoid-derived — Avoid derived state from URL parameters
• state-options-inheritance — Use withOptions for parser-level config
• state-setter-return — Use setter return value for URL access

4. Server Integration (HIGH)

• server-create-loader — Use createLoader for page-level server parsing
• server-search-params-cache — Use createSearchParamsCache for nested RSC access
• server-shallow-false — Use shallow:false to trigger server re-renders
• server-use-transition — Integrate useTransition for loading states
• server-share-parsers — Share parsers between client and server
• server-next15-async — Handle async searchParams in Next.js 15+

5. Performance (MEDIUM)

• perf-limit-url-updates — Throttle/debounce URL updates
• perf-clear-on-default — Use clearOnDefault for clean URLs
• perf-avoid-rerender — Memoize components using URL state
• perf-serialize-utility — Use createSerializer for link URLs

6. History & Navigation (MEDIUM)

• history-push-navigation — Use history:push for navigation-like state
• history-replace-ephemeral — Use history:replace for ephemeral state
• history-scroll-behavior — Control scroll behavior on URL changes
• history-back-sync — Handle browser back/forward navigation

7. Debugging & Testing (LOW-MEDIUM)

• debug-enable-logging — Enable debug logging for troubleshooting
• debug-common-errors — Diagnose common nuqs errors
• debug-testing — Test components and hooks with URL state

8. Advanced Patterns (LOW)

• advanced-url-keys — Use urlKeys for shorter URL param names
• advanced-eq-function — Implement eq function for object parsers
• advanced-adapter-props — Configure NuqsAdapter global defaults and URL middleware
• advanced-standard-schema — Use createStandardSchemaV1 and inferParserType
• advanced-optimistic-search-params — useOptimisticSearchParams for Remix/React Router