PluginBench
Skill
Pass
Audit score 90

nuqs

pproenca/dot-skills

Type-safe URL query state management best practices for Next.js and React frameworks.

SourceView on skills.sh

What is nuqs?

nuqs is a library for managing URL-based state in React and Next.js with full type safety. Use this skill when implementing, reviewing, or refactoring code that uses nuqs for URL parameters, search state, or query-based state management across Next.js, React Router, TanStack Router, Remix, and plain React.

  • Configure typed parsers for URL parameters with validation and defaults
  • Set up NuqsAdapter and 'use client' directives for proper initialization
  • Manage related URL parameters efficiently with useQueryStates
  • Integrate URL state with Next.js Server Components using createSearchParamsCache
  • Optimize performance with throttling, debouncing, and key isolation
  • Share parser definitions across libraries using Standard Schema

How to install nuqs

npx skills add https://github.com/pproenca/dot-skills --skill nuqs
Prerequisites
  • nuqs v2.5 or later installed
  • Next.js 13+ (or compatible React framework)
  • Understanding of React hooks and URL search parameters
Claude Code
Cursor
Windsurf
Cline

How to use nuqs

  1. 1.Define typed parsers in a shared file using nuqs parser utilities
  2. 2.Wrap your app with NuqsAdapter at the root level
  3. 3.Add 'use client' directive to components using useQueryState or useQueryStates hooks
  4. 4.Use useQueryStates for related parameters to reduce re-renders
  5. 5.Apply limitUrlUpdates for throttling rapid updates in search or filter scenarios
  6. 6.For Server Components, use createSearchParamsCache to parse URL parameters
  7. 7.Test components by mocking URL search parameters in your test setup

Use cases

Good for
  • Building search interfaces with URL-synced filters and pagination
  • Managing form state in URLs for shareable, bookmarkable forms
  • Implementing multi-step wizards with URL-based step tracking
  • Creating filterable product listings with persistent URL parameters
  • Syncing complex application state across browser tabs via URL
Who it's for
  • Next.js developers building state-driven applications
  • React developers using React Router or TanStack Router
  • Full-stack engineers integrating URL state with Server Components
  • Teams sharing validation schemas across tRPC, forms, and routing
  • Performance-conscious developers optimizing rapid state updates

nuqs FAQ

When should I use useQueryStates vs multiple useQueryState calls?

Use useQueryStates when managing related parameters together to batch updates and reduce re-renders. Use individual useQueryState calls only for independent parameters.

How do I prevent URL pollution with default values?

Use clearOnDefault option to automatically remove parameters from the URL when they match their default value, keeping URLs clean.

What's the difference between history:push and history:replace?

history:push adds a new entry to the browser history (default), allowing back-button navigation. history:replace overwrites the current entry, useful for intermediate states.

How do I share parsers between nuqs and tRPC or form validation?

Define parsers using Standard Schema (v2.5+) in a shared file, then use them with nuqs, tRPC, and form libraries that support Standard Schema.

Why is my Server Component not re-rendering when URL parameters change?

Use createSearchParamsCache or createLoader to parse URL parameters in Server Components, and set shallow:false on useQueryState to trigger server re-renders.

Full instructions (SKILL.md)

Source of truth, from pproenca/dot-skills.


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

PriorityCategoryImpactPrefix
1Parser ConfigurationCRITICALparser-
2Adapter & SetupCRITICALsetup-
3State ManagementHIGHstate-
4Server IntegrationHIGHserver-
5Performance OptimizationMEDIUMperf-
6History & NavigationMEDIUMhistory-
7Debugging & TestingLOW-MEDIUMdebug-
8Advanced PatternsLOWadvanced-

Quick Reference

1. Parser Configuration (CRITICAL)

2. Adapter & Setup (CRITICAL)

3. State Management (HIGH)

4. Server Integration (HIGH)

5. Performance Optimization (MEDIUM)

6. History & Navigation (MEDIUM)

7. Debugging & Testing (LOW-MEDIUM)

8. Advanced Patterns (LOW)

How to Use

Read individual reference files for detailed explanations and code examples:

Reference Files

FileDescription
AGENTS.mdComplete compiled guide with all rules
references/_sections.mdCategory definitions and ordering
assets/templates/_template.mdTemplate for new rules
metadata.jsonVersion and reference information

Related skills

More from pproenca/dot-skills and the wider catalog.