playbooks

home / skills / pproenca / dot-skills / nuqs

nuqs skill

/skills/.curated/nuqs

This skill enforces and guides type-safe URL query state practices in Next.js projects, improving reliability and maintainability when using nuqs.

npx playbooks add skill pproenca/dot-skills --skill nuqs

Review the files below or copy the command above to add this skill to your agents.

Files (48)
SKILL.md
6.6 KB
---
name: nuqs
description: nuqs (type-safe URL query state) best practices for Next.js applications. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, or Next.js routing with state.
---

# Community nuqs Best Practices for Next.js

Comprehensive guide for type-safe URL query state management with nuqs in Next.js applications. Contains 42 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 project
- Configuring parsers for URL parameters
- Integrating URL state with Server Components
- Optimizing URL update performance
- 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`](references/parser-use-typed-parsers.md) - Use typed parsers for non-string values
- [`parser-with-default`](references/parser-with-default.md) - Use withDefault for non-nullable state
- [`parser-enum-validation`](references/parser-enum-validation.md) - Use 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 input
- [`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

### 2. Adapter & Setup (CRITICAL)

- [`setup-nuqs-adapter`](references/setup-nuqs-adapter.md) - Wrap app with NuqsAdapter
- [`setup-use-client`](references/setup-use-client.md) - Add 'use client' directive for hooks
- [`setup-import-server`](references/setup-import-server.md) - Import server utilities from nuqs/server
- [`setup-nextjs-version`](references/setup-nextjs-version.md) - Ensure compatible Next.js version
- [`setup-shared-parsers`](references/setup-shared-parsers.md) - Define shared parsers in 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 configuration
- [`state-setter-return`](references/state-setter-return.md) - Use setter return value for URL access

### 4. Server Integration (HIGH)

- [`server-search-params-cache`](references/server-search-params-cache.md) - Use createSearchParamsCache for Server Components
- [`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-parse-before-get`](references/server-parse-before-get.md) - Call parse() before get() in Server Components
- [`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 Optimization (MEDIUM)

- [`perf-throttle-updates`](references/perf-throttle-updates.md) - Throttle rapid 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
- [`perf-debounce-search`](references/perf-debounce-search.md) - Debounce search input before URL update

### 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 with URL state

### 8. Advanced Patterns (LOW)

- [`advanced-custom-parsers`](references/advanced-custom-parsers.md) - Create custom parsers for complex types
- [`advanced-url-keys`](references/advanced-url-keys.md) - Use urlKeys for shorter URLs
- [`advanced-eq-function`](references/advanced-eq-function.md) - Implement eq function for object parsers
- [`advanced-framework-adapters`](references/advanced-framework-adapters.md) - Use framework-specific adapters

## How to Use

Read individual reference files for detailed explanations and code examples:

- [Section definitions](references/_sections.md) - Category structure and impact levels
- [Rule template](assets/templates/_template.md) - Template for adding new rules

## Reference Files

| File | Description |
|------|-------------|
| [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules |
| [references/_sections.md](references/_sections.md) | Category definitions and ordering |
| [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules |
| [metadata.json](metadata.json) | Version and reference information |

Overview

This skill provides concise, prioritized best practices for using nuqs (type-safe URL query state) in Next.js applications. It helps engineers implement, review, and refactor URL state management with clear rules for parsers, setup, server integration, and performance. Use it to reduce bugs, keep URLs clean, and ensure type-safe parameter handling across client and server components.

How this skill works

The skill inspects code and tasks that mention useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, and Next.js routing with state. It maps issues to a prioritized set of rules across parser configuration, adapter/setup, state management, server integration, performance, history, debugging, and advanced patterns. For each detected pattern it recommends concrete changes like using typed parsers, shared parser files, or createSearchParamsCache for Server Components.

When to use it

  • When adding or changing URL-driven state in a Next.js page or component
  • During code review or refactoring of components that read/write search params
  • When defining or updating nuqs parsers for non-string types (dates, arrays, enums)
  • When integrating URL state with Server Components or Next.js routing
  • When optimizing frequent URL updates or debouncing search inputs

Best practices

  • Use typed parsers for non-string values and withDefault to enforce non-nullable state
  • Wrap the app with NuqsAdapter and keep shared parsers in a dedicated file
  • Prefer useQueryStates for related params and use functional updates for derived changes
  • Share parsers between client and server and call parse() before get() in Server Components
  • Throttle or debounce rapid URL updates, use clearOnDefault to avoid noisy URLs
  • Choose history:push for navigation-like changes and history:replace for ephemeral state

Example use cases

  • Implementing filtered product lists where filters are stored in the URL with typed enums and arrays
  • Refactoring a page to move shared parsers into a common module used by server and client
  • Adding server-rendered components that read search params using createSearchParamsCache
  • Optimizing a live-search input by debouncing updates and using clearOnDefault to hide defaults
  • Handling browser back/forward with explicit history options and scroll behavior control

FAQ

When should I use useQueryStates vs multiple useQueryState calls?

Use useQueryStates for related parameters to read and set them together; prefer it when parameters form a cohesive set to avoid multiple URL writes and to keep updates atomic.

How do I avoid noisy URLs with default values?

Use parser withDefault and perf-clear-on-default (clearOnDefault) so default values are omitted from the URL, resulting in cleaner, shareable links.