nuqs

SKILL.md

Type-safe URL query state management for Next.js with 42 prioritized best practices across parser configuration, setup, and server integration.

Covers critical parser configuration (typed parsers, defaults, enums, arrays, JSON, dates) and adapter setup (NuqsAdapter, 'use client' directives, Next.js version compatibility)

Includes high-impact state management patterns using useQueryStates, functional updates, null clearing, and controlled inputs

Provides server integration guidance for Server Components, shallow rendering, useTransition integration, and Next.js 15+ async searchParams

Addresses performance optimization through throttling, debouncing, memoization, and URL serialization utilities

Covers history navigation modes (push vs. replace), debugging techniques, and advanced patterns like custom parsers and shorter URL keys

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