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.9 features. Contains 39 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

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-clear-with-null — Clear URL parameters with null
• 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-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 — Choose history:push vs history:replace
• history-scroll-behavior — Control scroll behavior on URL changes

7. Debugging & Testing (LOW-MEDIUM)

• debug-enable-logging — Enable debug logging for troubleshooting
• 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

Interactions

• Complements ahooks-v3 for grouped/local state not in the URL
• Complements tanstack-query-v5 for async server data (loading/error from queries)
• State decision tree: URL-shareable UI → nuqs; grouped ephemeral UI → ahooks; async data → TanStack Query