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 rapid 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
• •perf-debounce-search - Debounce search input before URL update

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
• •Rule template - Template for adding new rules

Reference Files