nuqs
Type-safe URL query state management with nuqs 2.x. Use when writing or reviewing code that uses useQueryState, useQueryStates, URL search params, query parameters, nuqs parsers, createLoader, createSearchParamsCache, createSerializer, or URL state in Next.js, React, Remix, React Router, or TanStack Router.
Best use case
nuqs is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
Type-safe URL query state management with nuqs 2.x. Use when writing or reviewing code that uses useQueryState, useQueryStates, URL search params, query parameters, nuqs parsers, createLoader, createSearchParamsCache, createSerializer, or URL state in Next.js, React, Remix, React Router, or TanStack Router.
Teams using nuqs should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/nuqs/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How nuqs Compares
| Feature / Agent | nuqs | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
Type-safe URL query state management with nuqs 2.x. Use when writing or reviewing code that uses useQueryState, useQueryStates, URL search params, query parameters, nuqs parsers, createLoader, createSearchParamsCache, createSerializer, or URL state in Next.js, React, Remix, React Router, or TanStack Router.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
Related Skills
solid
Apply SOLID principles to write flexible, maintainable, and testable code. Use when designing classes, interfaces, and module boundaries. Covers Single Responsibility, Open/Closed, Liskov Substitution, Interface Segregation, and Dependency Inversion with practical TypeScript examples and detection heuristics.
denji
Manage SVG icons as framework components using Denji CLI. Use when the user needs to add, remove, list, export, import, or manage SVG icons in React, Preact, Solid, Qwik, Vue, or Svelte projects. Triggers include requests to "add an icon", "set up icons", "manage SVG icons", "remove an icon", "list icons", "export icons", "import icons", "dry-run icon add", or any task involving Iconify icons as framework components.
zod
Zod 4 — TypeScript-first schema validation with static type inference. Use when writing Zod schemas, validating data, defining types with Zod, parsing input, creating form validation schemas, defining API request/response schemas, working with z.object, z.string, z.number, z.enum, z.array, z.union, z.discriminatedUnion, z.file, z.jwt, z.email, z.uuid, z.url, z.codec, z.toJSONSchema, z.fromJSONSchema, z.int, z.stringbool, z.templateLiteral, z.record, z.partialRecord, or any other Zod API. Also use when migrating from Zod 3 to Zod 4, or when the user's package.json shows zod@^4. CRITICAL: Always use Zod 4 APIs. Never use deprecated Zod 3 patterns unless user explicitly requests Zod 3 compatibility.
web-design-guidelines
Review UI code for Web Interface Guidelines compliance. Use when asked to "review my UI", "check accessibility", "audit design", "review UX", or "check my site against best practices".
vercel-react-best-practices
React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
vercel-composition-patterns
React composition patterns that scale. Use when refactoring components with boolean prop proliferation, building flexible component libraries, or designing reusable APIs. Triggers on tasks involving compound components, render props, context providers, or component architecture. Includes React 19 API changes.
turborepo
Turborepo monorepo build system guidance. Triggers on: turbo.json, task pipelines, dependsOn, caching, remote cache, the "turbo" CLI, --filter, --affected, CI optimization, environment variables, internal packages, monorepo structure/best practices, and boundaries. Use when user: configures tasks/workflows/pipelines, creates packages, sets up monorepo, shares code between apps, runs changed/affected packages, debugs cache, or has apps/packages directories.
tanstack-virtual
TanStack Virtual headless virtualization for React. Use when rendering large lists (100+ items), implementing virtual scroll, building infinite scroll feeds, virtualizing grids or tables, using window-level scrolling, or implementing masonry/lane layouts with @tanstack/react-virtual. Triggers on: useVirtualizer, useWindowVirtualizer, virtual list, virtual scroll, list virtualization.
tanstack-query
TanStack Query (React Query) v5 best practices for data fetching, caching, mutations, and server state management. Use when building data-driven React applications, setting up query configurations, implementing mutations/optimistic updates, configuring caching strategies, integrating with SSR, or fixing v4→v5 migration errors.
tanstack-pacer
TanStack Pacer best practices for execution control in React — debouncing, throttling, rate limiting, queuing, and batching. Use when implementing search inputs, scroll handlers, API rate limits, task queues, bulk operations, or any scenario requiring controlled execution timing with reactive state.
tanstack-hotkeys
Guide for implementing keyboard shortcuts in React using @tanstack/react-hotkeys. Use when building hotkey/shortcut features, registering keyboard shortcuts, handling key sequences, recording custom shortcuts, tracking held keys, or formatting hotkeys for display in React applications.
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Claude's capabilities with specialized knowledge, workflows, or tool integrations.