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
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.
seo-audit
When the user wants to audit, review, or diagnose SEO issues on their site. Also use when the user mentions "SEO audit," "technical SEO," "why am I not ranking," "SEO issues," "on-page SEO," "meta tags review," or "SEO health check." For building pages at scale to target keywords, see programmatic-seo. For adding structured data, see schema-markup.
next-upgrade
Upgrade Next.js to the latest version following official migration guides and codemods
next-cache-components
Next.js 16 Cache Components - PPR, use cache directive, cacheLife, cacheTag, updateTag
kanpeki
Use Kanpeki component library in React projects. Activate when user wants to add, use, customize, or compose accessible UI components from Kanpeki (@kanpeki/*). Covers installation, component patterns, forms, theming, and dark mode with React Aria Components + Tailwind CSS 4.1 + CVA.
interface-design
This skill is for interface design — dashboards, admin panels, apps, tools, and interactive products. NOT for marketing design (landing pages, marketing sites, campaigns).
frontend-design
Create distinctive, production-grade frontend interfaces with high design quality. Use this skill when the user asks to build web components, pages, or applications. Generates creative, polished code that avoids generic AI aesthetics.
denji
Manage SVG icons as framework components using Denji CLI. Use when the user needs to add, remove, list, 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", or any task involving Iconify icons as framework components.
commit-work
Create high-quality git commits: review/stage intended changes, split into logical commits, and write clear commit messages (including Conventional Commits). Use when the user asks to commit, craft a commit message, stage changes, or split work into multiple commits.
clean-code
Write clean, readable, and maintainable code following principles from Robert C. Martin's "Clean Code" and Object Calisthenics. Use when writing, reviewing, or refactoring code to improve naming, function design, formatting, error handling, and class structure. Includes code smell detection and refactoring guidance.