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