nuqs

SKILL.md

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 — 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

setup-default-options — Configure app-wide defaults on NuqsAdapter (v2.5+)

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

state-standard-schema — Use Standard Schema for cross-library validation (v2.5+)

4. Server Integration (HIGH)

server-search-params-cache — Use createSearchParamsCache (or createLoader) 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 with limitUrlUpdates

perf-debounce-search — Debounce search input with built-in limitUrlUpdates

perf-clear-on-default — Use clearOnDefault for clean URLs

perf-avoid-rerender — Memoize components using URL state (Next.js)

perf-key-isolation — Rely on key isolation outside Next.js (v2.5+)

perf-serialize-utility — Use createSerializer for link URLs

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

advanced-process-url-search-params — Canonicalize URL shape with processUrlSearchParams (v2.6+)

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