nuqs

Version 0.1.0
Community
January 2026

Note:
This document is mainly for agents and LLMs to follow when maintaining,
generating, or refactoring codebases. 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 applications, designed for AI agents and LLMs. Contains 42 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 from malformed URL data)
2. Adapter & Setup — CRITICAL
   • 2.1 Add 'use client' Directive for Hooks — CRITICAL (prevents build-breaking hook errors in RSC)
   • 2.2 Define Shared Parsers in Dedicated File — HIGH (prevents parser mismatch bugs between components)
   • 2.3 Ensure Compatible Next.js Version — CRITICAL (prevents cryptic runtime errors from version mismatch)
   • 2.4 Import Server Utilities from nuqs/server — CRITICAL (prevents RSC-to-client boundary contamination errors)
   • 2.5 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)
   • 3.6 Use useQueryStates for Related Parameters — HIGH (atomic updates prevent intermediate invalid states)
   • 3.7 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 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 — MEDIUM (reduces server requests during typing)
   • 5.2 Memoize Components Using URL State — MEDIUM (prevents unnecessary re-renders on URL changes)
   • 5.3 Throttle Rapid URL Updates — MEDIUM (prevents browser history API rate limiting)
   • 5.4 Use clearOnDefault for Clean URLs — MEDIUM (reduces URL length by 20-50% for default values)
   • 5.5 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 urlKeys for Shorter URLs — LOW (reduces URL length by 50-70% for verbose params)

References

1. https://nuqs.dev
2. https://github.com/47ng/nuqs
3. https://nextjs.org/docs
4. https://react.dev

Source Files

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