Nuqs

nuqs Best Practices

Type-safe URL query state management with nuqs 2.x. Contains rules across 8 categories, prioritized by impact.

Rule Categories

| 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 | 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-typed](references/parser-typed.md) — Use typed parsers for non-string values
• [parser-with-default](references/parser-with-default.md) — Use withDefault for non-nullable state
• [parser-enum-literals](references/parser-enum-literals.md) — Use literal/enum parsers for constrained values
• [parser-array-format](references/parser-array-format.md) — Choose correct array parser format
• [parser-json-validation](references/parser-json-validation.md) — Validate JSON parser with Standard Schema
• [parser-date-format](references/parser-date-format.md) — Select appropriate date parser
• [parser-index-offset](references/parser-index-offset.md) — Use parseAsIndex for 1-based URL display
• [parser-hex-colors](references/parser-hex-colors.md) — Use parseAsHex for color values
• [parser-custom](references/parser-custom.md) — Create custom parsers for complex types

2. Adapter & Setup (CRITICAL)

• [setup-adapter](references/setup-adapter.md) — Wrap app with correct NuqsAdapter
• [setup-client-hooks](references/setup-client-hooks.md) — Add 'use client' for hooks
• [setup-server-imports](references/setup-server-imports.md) — Import server utilities from nuqs/server
• [setup-shared-parsers](references/setup-shared-parsers.md) — Define shared parsers in a dedicated file

3. State Management (HIGH)

• [state-use-query-states](references/state-use-query-states.md) — Use useQueryStates for related parameters
• [state-functional-updates](references/state-functional-updates.md) — Use functional updates for derived state
• [state-clear-with-null](references/state-clear-with-null.md) — Clear URL parameters with null
• [state-controlled-inputs](references/state-controlled-inputs.md) — Handle controlled input value properly
• [state-avoid-derived](references/state-avoid-derived.md) — Avoid derived state from URL parameters
• [state-options-inheritance](references/state-options-inheritance.md) — Use withOptions for parser-level config
• [state-setter-return](references/state-setter-return.md) — Use setter return value for URL access

4. Server Integration (HIGH)

• [server-create-loader](references/server-create-loader.md) — Use createLoader for page-level server parsing
• [server-search-params-cache](references/server-search-params-cache.md) — Use createSearchParamsCache for nested RSC access
• [server-shallow-false](references/server-shallow-false.md) — Use shallow:false to trigger server re-renders
• [server-use-transition](references/server-use-transition.md) — Integrate useTransition for loading states
• [server-share-parsers](references/server-share-parsers.md) — Share parsers between client and server
• [server-next15-async](references/server-next15-async.md) — Handle async searchParams in Next.js 15+

5. Performance (MEDIUM)

• [perf-limit-url-updates](references/perf-limit-url-updates.md) — Throttle/debounce URL updates
• [perf-clear-on-default](references/perf-clear-on-default.md) — Use clearOnDefault for clean URLs
• [perf-avoid-rerender](references/perf-avoid-rerender.md) — Memoize components using URL state
• [perf-serialize-utility](references/perf-serialize-utility.md) — Use createSerializer for link URLs

6. History & Navigation (MEDIUM)

• [history-push-navigation](references/history-push-navigation.md) — Use history:push for navigation-like state
• [history-replace-ephemeral](references/history-replace-ephemeral.md) — Use history:replace for ephemeral state
• [history-scroll-behavior](references/history-scroll-behavior.md) — Control scroll behavior on URL changes
• [history-back-sync](references/history-back-sync.md) — Handle browser back/forward navigation

7. Debugging & Testing (LOW-MEDIUM)

• [debug-enable-logging](references/debug-enable-logging.md) — Enable debug logging for troubleshooting
• [debug-common-errors](references/debug-common-errors.md) — Diagnose common nuqs errors
• [debug-testing](references/debug-testing.md) — Test components and hooks with URL state

8. Advanced Patterns (LOW)

• [advanced-url-keys](references/advanced-url-keys.md) — Use urlKeys for shorter URL param names
• [advanced-eq-function](references/advanced-eq-function.md) — Implement eq function for object parsers
• [advanced-adapter-props](references/advanced-adapter-props.md) — Configure NuqsAdapter global defaults and URL middleware
• [advanced-standard-schema](references/advanced-standard-schema.md) — Use createStandardSchemaV1 and inferParserType
• [advanced-optimistic-search-params](references/advanced-optimistic-search-params.md) — useOptimisticSearchParams for Remix/React Router

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: fellipeutaka
• Source: fellipeutaka/leon
• License: MIT

Install and usage instructions live in the source repository linked above.