nuqs

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` — Use typed parsers for non-string values
• `parser-with-default` — Use withDefault for non-nullable state
• `parser-enum-validation` — Use enum parsers for constrained values
• `parser-array-format` — Choose correct array parser format
• `parser-json-validation` — Validate JSON parser input
• `parser-date-format` — Select appropriate date parser
• `parser-index-offset` — Use parseAsIndex for 1-based URL display

2. Adapter & Setup (CRITICAL)

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

3. State Management (HIGH)

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

4. Server Integration (HIGH)

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

5. Performance Optimization (MEDIUM)

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

6. History & Navigation (MEDIUM)

• `history-push-navigation` — Choose history:push vs history:replace
• `history-scroll-behavior` — Control scroll behavior on URL changes

7. Debugging & Testing (LOW-MEDIUM)

• `debug-enable-logging` — Enable debug logging for troubleshooting
• `debug-testing` — Test components with URL state

8. Advanced Patterns (LOW)

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

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions — Category structure and impact levels
• Rule template — Template for adding new rules

Reference Files