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