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

parser-

setup-

state-

server-

perf-

history-

debug-

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