Skip to main content
affpapa.org
RU EN
skill CX Codex

nuqs — Claude Code skill: URL state rules for React

A skill with 39 nuqs rules covering typed parsers, adapters, Server Components and URL update performance. Useful when an agent writes or refactors URL state code.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add pproenca/dot-skills --skill nuqs -a claude-code
Open on GitHub

What nuqs does

This skill collects best practices for nuqs, the type-safe URL query state library for Next.js and other React frameworks. It ships 39 rules in 8 categories ordered by impact: parser configuration and adapter setup come first, then state management, server integration, performance, history and navigation, debugging, and advanced patterns. Each rule lives in its own file under references/ with an explanation and code samples, and AGENTS.md compiles them into one guide.

The agent pulls the skill in when a task mentions useQueryState, useQueryStates, search params, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state. Coverage spans nuqs v2.5–v2.9, including createLoader, processUrlSearchParams, and key isolation outside Next.js. Server sections call out shallow:false, useTransition, and async searchParams in Next.js 15+.

Nothing runs against your codebase — it is a rule set for generation and review. If your project does not use nuqs, the rules have nothing to attach to. Installing needs Node.js with npx, or gh for GitHub Copilot.

What it helps with

  • pick a typed parser instead of a string one for numbers or dates
  • wire up NuqsAdapter and the 'use client' directive in a new app
  • connect URL state to Server Components with createSearchParamsCache
  • stop redundant URL updates while typing in a search box
  • track down why params fail to parse in Next.js 15

Example prompts for the agent

  • add nuqs for the catalog filters and keep the state in the URL
  • refactor this component to useQueryStates and move the parsers into a shared file
  • searchParams aren't parsing in my Server Component — check it against the nuqs rules

How to install nuqs

1Skills CLI (Vercel)

npx skills add pproenca/dot-skills --skill nuqs -a claude-code

2Manually: put the files in place

~/.claude/skills/nuqs/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/nuqs/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about nuqs

How do I install nuqs in Claude?

Run npx skills add pproenca/dot-skills --skill nuqs -a claude-code. The skill lands at ~/.claude/skills/nuqs/SKILL.md.

What does the nuqs skill do?

It gives the agent 39 rules for nuqs: parsers, adapters, server integration, performance, and debugging. The agent applies them while writing, reviewing, or refactoring URL state code.

Which frameworks does the skill cover?

Next.js, React Router, TanStack Router, Remix, and plain React. It covers nuqs v2.5–v2.9.

Source text

SKILL.md · MIT 
---
name: nuqs
description: nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. 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, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.
---

# 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`](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

### 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
- [`setup-default-options`](references/setup-default-options.md) — Configure app-wide defaults on NuqsAdapter (v2.5+)

### 3. State Management (HIGH)

- [`state-use-query-states`](references/state-use-query-states.md) — Use useQueryStates for related parameters
- [`state-clear-with-null`](references/state-clear-with-null.md) — Clear URL parameters with null
- [`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
- [`state-standard-schema`](references/state-standard-schema.md) — Use Standard Schema for cross-library validation (v2.5+)

### 4. Server Integration (HIGH)

- [`server-search-params-cache`](references/server-search-params-cache.md) — Use createSearchParamsCache (or createLoader) 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-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 with `limitUrlUpdates`
- [`perf-debounce-search`](references/perf-debounce-search.md) — Debounce search input with built-in `limitUrlUpdates`
- [`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 (Next.js)
- [`perf-key-isolation`](references/perf-key-isolation.md) — Rely on key isolation outside Next.js (v2.5+)
- [`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) — Choose history:push vs history:replace
- [`history-scroll-behavior`](references/history-scroll-behavior.md) — Control scroll behavior on URL changes

### 7. Debugging & Testing (LOW-MEDIUM)

- [`debug-enable-logging`](references/debug-enable-logging.md) — Enable debug logging for troubleshooting
- [`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
- [`advanced-process-url-search-params`](references/advanced-process-url-search-params.md) — Canonicalize URL shape with `processUrlSearchParams` (v2.6+)

## 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 |

© pproenca · MIT · pproenca/dot-skills

Similar skills

Everything for Frontend and UI →
frontend-patterns affaan-m A skill for React and Next.js work: component patterns, state, data fetching, and render performance. Use it when building or reviewing UI. CX Codex +1 5,900installs senior-frontend Alireza Rezvani This skill supports React and Next.js work, from project scaffolding to bundle checks. Use it when building components, reviewing frontend code, or working on accessibility. 1,630installs redux-toolkit Mindrally Redux Toolkit best practices for React and Next.js applications using TypeScript. Helps structure feature slices, typed hooks, and RTK Query endpoints. CX Codex +1 1,300installs zustand-state-management Mindrally Enforces Zustand store best practices in React and TypeScript apps, covering store slices, SSR, and testing. It helps eliminate selector re-renders and hydration bugs. CX Codex +1 959installs senior-fullstack borghei Generates production-ready project templates for Next.js, FastAPI, MERN, or Django, and runs static quality audits on existing codebases. CX Codex +1 311installs nextjs-code-quality-enforcer davila7 A PostToolUse hook that checks every Next.js file you write: App Router structure, Server and Client Component directives, imports, types. It runs right after an edit. 2,249installs

From the same set45

vitest Equips your coding agent with 44 prioritized rules for writing, debugging, and speeding up Vitest suites. Covers async patterns, mocks, and test isolation. CX Codex +1 6,100installs react-hook-form Optimizes client-side forms using React Hook Form 7.82.0 and prevents unnecessary re-renders across field subscriptions, validation, and controlled UI inputs. CX Codex +1 3,000installs emilkowal-animations A set of 58 web animation rules based on Emil Kowalski's work for React and Framer Motion. Helps tune easing curves, gestures, and UI timing. CX Codex +1 2,800installs clean-architecture A skill with 42 rules from Robert C. Martin's book: it tells the agent which way dependencies should point and where layer boundaries belong. CX Codex +1 2,000installs code-simplifier A skill that gives AI agents 47 rules for cleaning up recently changed code without altering what it does. CX Codex +1 1,600installs expo-react-native-performance Performance guidelines with 42 prioritized rules for Expo React Native apps. Helps agents refactor startup bottlenecks, list virtualization, re-renders, and animations. CX Codex +1 1,500installs framer-motion Optimizes React animations using Framer Motion guidelines: slashes bundle size, eliminates unnecessary re-renders, and polishes gesture or scroll transitions. CX Codex +1 1,100installs msw A skill with 45 rules for Mock Service Worker v2: setup, handlers, test integration, GraphQL. Useful when your agent writes or fixes HTTP mocks. CX Codex +1 842installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor