Nuqs

# Community nuqs Best Practices for Next.js & React

Comprehensive guide for type-safe URL query state management with nuqs across Next.js, React Router, TanStack Router, Remix, and plain React. Covers nuqs v2.5–v2.8 features. Contains 46 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 or React Router project
- Configuring parsers for URL parameters
- Integrating URL state with Server Components
- Optimizing URL update performance (`limitUrlUpdates`, key isolation)
- Sharing parser definitions with tRPC / TanStack Router / forms via Standard Schema
- 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`](references/parser-use-typed-parsers.md) — Use typed parsers for non-string values
- [`parser-with-default`](references/parser-with-default.md) — Use withDefault for non-nullable state
- [`parser-enum-validation`](references/parser-enum-validation.md) — Use enum parsers for constrained values
- [`parser-array-format`](references/parser-array-format.md) — Choose correct array parser format
- [`parser-json-validation`](references/parser-json-validation.md) — Validate JSON parser input
- [`parser-date-format`](references/parser-date-format.md) — Select appropriate date parser
- [`parser-index-offset`](references/parser-index-offset.md) — Use parseAsIndex for 1-based URL display
- [`parser-hex-colors`](references/parser-hex-colors.md) — Use parseAsHex for color values

### 2. Adapter & Setup (CRITICAL)

- [`setup-nuqs-adapter`](references/setup-nuqs-adapter.md) — Wrap app with NuqsAdapter
- [`setup-use-client`](references/setup-use-client.md) — Add 'use client' directive for hooks
- [`setup-import-server`](references/setup-import-server.md) — Import server utilities from nuqs/server
- [`setup-nextjs-version`](references/setup-nextjs-version.md) — Ensure compatible Next.js version
- [`setup-shared-parsers`](references/setup-shared-parsers.md) — Define shared parsers in dedicated file
- [`setup-default-options`](references/setup-default-options.md) — Configure app-wide defaults on NuqsAdapter (v2.5+)

### 3. State Management (HIGH)

- [`state-use-query-states`](references/state-use-query-states.md) — Use useQueryStates for related parameters
- [`state-functional-updates`](references/state-functional-updates.md) — Use functional updates for derived state
- [`state-clear-with-null`](references/state-clear-with-null.md) — Clear URL parameters with null
- [`state-controlled-inputs`](references/state-controlled-inputs.md) — Handle controlled input value properly
- [`state-avoid-derived`](references/state-avoid-derived.md) — Avoid derived state from URL parameters
- [`state-options-inheritance`](references/state-options-inheritance.md) — Use withOptions for parser-level configuration
- [`state-setter-return`](references/state-setter-return.md) — Use setter return value for URL acce