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