nuqs

Community nuqs Best Practices for Next.js

Comprehensive guide for type-safe URL query state management with nuqs in Next.js applications. Contains 42 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 project
• Configuring parsers for URL parameters
• Integrating URL state with Server Components
• Optimizing URL update performance
• 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
• `parser-hex-colors` - Use parseAsHex for color values

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

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 configuration
• `state-setter-return` - Use setter return value for URL access

4. Server Integration (HIGH)

• `server-search-params-cache` - Use createSearchParamsCache 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-share-parsers` - Share parsers between client and server
• `server-next15-async` - Handle async searchParams in Next.js 15+

5. Performance Optimization (MEDIUM)

• `perf-throttle-updates` - Throttle URL updates with limitUrlUpdates
• `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
• `perf-debounce-search` - Debounce server-bound search updates

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 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

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels

Reference Files