Community nuqs Best Practices for Next.js & React

Comprehensive guide for type-safe URL query state management with nuqs across Next.js, React Router, TanStack Router, Remix, and plain React. Covers nuqs v2.5–v2.9 features. Contains 39 rules across 8 categories, prioritized by impact to guide code generation, refactoring, and code review.

When to Apply

Reference these guidelines when:

• Implementing URL-based state with nuqs
• Setting up nuqs in a Next.js or React Router project
• Configuring parsers for URL parameters
• Integrating URL state with Server Components
• Optimizing URL update performance (limitUrlUpdates, key isolation)
• Sharing parser definitions with tRPC / TanStack Router / forms via Standard Schema
• Debugging nuqs-related issues

Rule Categories by Priority

Quick Reference

1. Parser Configuration (CRITICAL)

• [parser-use-typed-parsers](references/parser-use-typed-parsers.md) — Use typed parsers for non-string values
• [parser-with-default](references/parser-with-default.md) — Use withDefault for non-nullable state
• [parser-enum-validation](references/parser-enum-validation.md) — Use enum parsers for constrained values
• [parser-array-format](references/parser-array-format.md) — Choose correct array parser format
• [parser-json-validation](references/parser-json-validation.md) — Validate JSON parser input
• [parser-date-format](references/parser-date-format.md) — Select appropriate date parser
• [parser-index-offset](references/parser-index-offset.md) — Use parseAsIndex for 1-based URL display

2. Adapter & Setup (CRITICAL)

• [setup-nuqs-adapter](references/setup-nuqs-adapter.md) — Wrap app with NuqsAdapter
• [setup-use-client](references/setup-use-client.md) — Add 'use client' directive for hooks
• [setup-import-server](references/setup-import-server.md) — Import server utilities from nuqs/server
• [setup-nextjs-version](references/setup-nextjs-version.md) — Ensure compatible Next.js version
• [setup-shared-parsers](references/setup-shared-parsers.md) — Define shared parsers in dedicated file
• [setup-default-options](references/setup-default-options.md) — Configure app-wide defaults on NuqsAdapter (v2.5+)

3. State Management (HIGH)

• [state-use-query-states](references/state-use-query-states.md) — Use useQueryStates for related parameters
• [state-clear-with-null](references/state-clear-with-null.md) — Clear URL parameters with null
• [state-avoid-derived](references/state-avoid-derived.md) — Avoid derived state from URL parameters
• [state-options-inheritance](references/state-options-inheritance.md) — Use withOptions for parser-level configuration
• [state-setter-return](references/state-setter-return.md) — Use setter return value for URL access
• [state-standard-schema](references/state-standard-schema.md) — Use Standard Schema for cross-library validation (v2.5+)

4. Server Integration (HIGH)

• [server-search-params-cache](references/server-search-params-cache.md) — Use createSearchParamsCache (or createLoader) for Server Components
• [server-shallow-false](references/server-shallow-false.md) — Use shallow:false to trigger server re-renders
• [server-use-transition](references/server-use-transition.md) — Integrate useTransition for loading states
• [server-parse-before-get](references/server-parse-before-get.md) — Call parse() before get() in Server Components
• [server-next15-async](references/server-next15-async.md) — Handle async searchParams in Next.js 15+

5. Performance Optimization (MEDIUM)

• [perf-throttle-updates](references/perf-throttle-updates.md) — Throttle rapid URL updates with limitUrlUpdates
• [perf-debounce-search](references/perf-debounce-search.md) — Debounce search input with built-in limitUrlUpdates
• [perf-clear-on-default](references/perf-clear-on-default.md) — Use clearOnDefault for clean URLs
• [perf-avoid-rerender](references/perf-avoid-rerender.md) — Memoize components using URL state (Next.js)
• [perf-key-isolation](references/perf-key-isolation.md) — Rely on key isolation outside Next.js (v2.5+)
• [perf-serialize-utility](references/perf-serialize-utility.md) — Use createSerializer for link URLs

6. History & Navigation (MEDIUM)

• [history-push-navigation](references/history-push-navigation.md) — Choose history:push vs history:replace
• [history-scroll-behavior](references/history-scroll-behavior.md) — Control scroll behavior on URL changes

7. Debugging & Testing (LOW-MEDIUM)

• [debug-enable-logging](references/debug-enable-logging.md) — Enable debug logging for troubleshooting
• [debug-testing](references/debug-testing.md) — Test components with URL state

8. Advanced Patterns (LOW)

• [advanced-custom-parsers](references/advanced-custom-parsers.md) — Create custom parsers for complex types
• [advanced-url-keys](references/advanced-url-keys.md) — Use urlKeys for shorter URLs
• [advanced-eq-function](references/advanced-eq-function.md) — Implement eq function for object parsers
• [advanced-framework-adapters](references/advanced-framework-adapters.md) — Use framework-specific adapters
• [advanced-process-url-search-params](references/advanced-process-url-search-params.md) — Canonicalize URL shape with processUrlSearchParams (v2.6+)

How to Use

Read individual reference files for detailed explanations and code examples:

• [Section definitions](references/_sections.md) — Category structure and impact levels
• [Rule template](assets/templates/_template.md) — Template for adding new rules

Reference Files