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 Priority Category Impact Prefix 1 Parser Configuration CRITICAL parser- 2 Adapter & Setup CRITICAL setup- 3 State Management HIGH state- 4 Server Integration HIGH server- 5 Performance Optimization MEDIUM perf- 6 History & Navigation MEDIUM history- 7 Debugging & Testing LOW-MEDIUM debug- 8 Advanced Patterns LOW advanced- 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 File Description AGENTS.md Complete compiled guide with all rules references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information