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