Imported from day-mon/dotfiles (.claude/skills/nuqs/AGENTS.md). Install upstream with npx skills add day-mon/dotfiles --skill nuqs. Copyright stays with the author.

nuqs

Version 1.2.0
Community
May 2026

Note:
This nuqs best-practices document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases that use nuqs. Humans may also find it useful,
but guidance here is optimized for automation and consistency by AI-assisted workflows.

Abstract

Comprehensive best practices guide for nuqs (type-safe URL query state management) in Next.js and other React frameworks, designed for AI agents and LLMs. Covers nuqs v2.5–v2.8 features including limitUrlUpdates (built-in debounce/throttle), key isolation, Standard Schema integration, defaultOptions on NuqsAdapter, processUrlSearchParams middleware, and the createLoader server utility. Contains 46 rules across 8 categories, prioritized by impact from critical (parser configuration, adapter setup) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples comparing incorrect vs. correct implementations, and specific impact metrics to guide automated refactoring and code generation.

Table of Contents

1. Parser Configuration — CRITICAL
   • 1.1 Choose Correct Array Parser Format — CRITICAL (prevents API integration failures from wrong URL format)
   • 1.2 Select Appropriate Date Parser — CRITICAL (prevents timezone bugs and parsing failures)
   • 1.3 Use Enum Parsers for Constrained Values — CRITICAL (prevents invalid state from URL manipulation)
   • 1.4 Use parseAsHex for Color Values — MEDIUM (50% shorter URLs for color parameters)
   • 1.5 Use parseAsIndex for 1-Based URL Display — HIGH (eliminates off-by-one errors between URL and code)
   • 1.6 Use Typed Parsers for Non-String Values — CRITICAL (prevents runtime type errors and hydration mismatches)
   • 1.7 Use withDefault for Non-Nullable State — CRITICAL (eliminates null checks throughout component tree)
   • 1.8 Validate JSON Parser Input — CRITICAL (prevents runtime crashes and unsafe casts from URL-supplied JSON)
2. Adapter & Setup — CRITICAL
   • 2.1 Add 'use client' Directive for Hooks — CRITICAL (prevents build-breaking hook errors in RSC)
   • 2.2 Configure App-Wide Defaults on NuqsAdapter — MEDIUM (avoids repeating .withOptions on every parser; enforces consistent behaviour)
   • 2.3 Define Shared Parsers in Dedicated File — HIGH (prevents parser mismatch bugs between components)
   • 2.4 Ensure Compatible Next.js Version — CRITICAL (prevents cryptic runtime errors from version mismatch)
   • 2.5 Import Server Utilities from nuqs/server — CRITICAL (prevents RSC-to-client boundary contamination errors)
   • 2.6 Wrap App with NuqsAdapter — CRITICAL (prevents 100% of hook failures from missing provider)
3. State Management — HIGH
   • 3.1 Avoid Derived State from URL Parameters — HIGH (prevents sync bugs and unnecessary re-renders)
   • 3.2 Clear URL Parameters with null — HIGH (reduces URL clutter by removing unnecessary parameters)
   • 3.3 Handle Controlled Input Value Properly — HIGH (prevents uncontrolled to controlled warnings)
   • 3.4 Use Functional Updates for State Derived from Previous Value — HIGH (prevents stale closure bugs and race conditions)
   • 3.5 Use Setter Return Value for URL Access — MEDIUM (enables accurate URL tracking for analytics/sharing without re-deriving the URL)
   • 3.6 Use Standard Schema for Cross-Library Validation — MEDIUM (eliminates 2-4× duplicate schema definitions across nuqs, tRPC, route validators, and forms)
   • 3.7 Use useQueryStates for Related Parameters — HIGH (gives a single typed object and one combined URLSearchParams flush)
   • 3.8 Use withOptions for Parser-Level Configuration — MEDIUM (reduces boilerplate and ensures consistent behavior)
4. Server Integration — HIGH
   • 4.1 Call parse() Before get() in Server Components — HIGH (prevents undefined values and runtime errors)
   • 4.2 Handle Async searchParams in Next.js 15+ — HIGH (prevents build errors in Next.js 15 with async props)
   • 4.3 Integrate useTransition for Loading States — HIGH (100% visibility into server fetch pending state)
   • 4.4 Share Parsers Between Client and Server — HIGH (prevents client/server hydration mismatches)
   • 4.5 Use createSearchParamsCache (or createLoader) for Server Components — HIGH (eliminates prop drilling across N component levels)
   • 4.6 Use shallow:false to Trigger Server Re-renders — HIGH (enables server-side data refetching on URL change)
5. Performance Optimization — MEDIUM
   • 5.1 Debounce Search Input Before URL Update — HIGH (reduces server requests during typing from N per keystroke to 1 per pause)
   • 5.2 Memoize Components Using URL State — MEDIUM (prevents unnecessary re-renders on URL changes — Next.js especially)
   • 5.3 Rely on Key Isolation Outside Next.js — HIGH (avoids unnecessary memoization on adapters that already scope re-renders per key)
   • 5.4 Throttle Rapid URL Updates — MEDIUM (prevents browser history API rate limiting on rapid input)
   • 5.5 Use clearOnDefault for Clean URLs — MEDIUM (reduces URL length by 20-50% for default values)
   • 5.6 Use createSerializer for Link URLs — MEDIUM (enables SSR-compatible URL generation without hooks)
6. History & Navigation — MEDIUM
   • 6.1 Control Scroll Behavior on URL Changes — MEDIUM (prevents jarring scroll jumps on state changes)
   • 6.2 Handle Browser Back/Forward Navigation — MEDIUM (prevents stale UI after browser navigation)
   • 6.3 Use history:push for Navigation-Like State — MEDIUM (enables back button for state navigation)
   • 6.4 Use history:replace for Ephemeral State — MEDIUM (prevents history pollution from frequent updates)
7. Debugging & Testing — LOW-MEDIUM
   • 7.1 Diagnose Common nuqs Errors — LOW-MEDIUM (reduces debugging time from hours to minutes)
   • 7.2 Enable Debug Logging for Troubleshooting — LOW-MEDIUM (reduces debugging time by 5-10×)
   • 7.3 Test Components with URL State — LOW-MEDIUM (enables reliable CI/CD testing of nuqs components)
8. Advanced Patterns — LOW
   • 8.1 Create Custom Parsers for Complex Types — LOW (prevents runtime errors from string coercion)
   • 8.2 Implement eq Function for Object Parsers — LOW (prevents unnecessary URL updates for equivalent objects)
   • 8.3 Use Framework-Specific Adapters — LOW (prevents URL sync failures in non-Next.js apps)
   • 8.4 Use processUrlSearchParams for Canonical URL Shape — LOW-MEDIUM (enables stable URL ordering for SEO and cache hit-rate)
   • 8.5 Use urlKeys for Shorter URLs — LOW (reduces URL length by 50-70% for verbose params)

References

1. https://nuqs.dev
2. https://nuqs.dev/blog/nuqs-2.5
3. https://github.com/47ng/nuqs
4. https://nextjs.org/docs
5. https://react.dev
6. https://standardschema.dev

Source Files

This document was compiled from individual reference files. For detailed editing or extension: