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