nuqs

Original：🇺🇸 English

Translated

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.

2installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills nuqs

SKILL.md Content

View Translation Comparison →

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


parser-
setup-
state-
server-
perf-
history-
debug-
advanced-

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
```
- Use typed parsers for non-string values
```
parser-with-default
```
- Use withDefault for non-nullable state
```
parser-enum-validation
```
- Use enum parsers for constrained values
```
parser-array-format
```
- Choose correct array parser format
```
parser-json-validation
```
- Validate JSON parser input
```
parser-date-format
```
- Select appropriate date parser
```
parser-index-offset
```
- Use parseAsIndex for 1-based URL display
```
parser-hex-colors
```
- Use parseAsHex for color values

2. Adapter & Setup (CRITICAL)

```
setup-nuqs-adapter
```
- Wrap app with NuqsAdapter
```
setup-use-client
```
- Add 'use client' directive for hooks
```
setup-import-server
```
- Import server utilities from nuqs/server
```
setup-nextjs-version
```
- Ensure compatible Next.js version
```
setup-shared-parsers
```
- Define shared parsers in dedicated file

3. State Management (HIGH)

```
state-use-query-states
```
- Use useQueryStates for related parameters
```
state-functional-updates
```
- Use functional updates for derived state
```
state-clear-with-null
```
- Clear URL parameters with null
```
state-controlled-inputs
```
- Handle controlled input value properly
```
state-avoid-derived
```
- Avoid derived state from URL parameters
```
state-options-inheritance
```
- Use withOptions for parser-level configuration
```
state-setter-return
```
- Use setter return value for URL access

4. Server Integration (HIGH)

```
server-search-params-cache
```
- Use createSearchParamsCache for Server Components
```
server-shallow-false
```
- Use shallow:false to trigger server re-renders
```
server-use-transition
```
- Integrate useTransition for loading states
```
server-parse-before-get
```
- Call parse() before get() in Server Components
```
server-share-parsers
```
- Share parsers between client and server
```
server-next15-async
```
- Handle async searchParams in Next.js 15+

5. Performance Optimization (MEDIUM)

```
perf-throttle-updates
```
- Throttle rapid URL updates
```
perf-clear-on-default
```
- Use clearOnDefault for clean URLs
```
perf-avoid-rerender
```
- Memoize components using URL state
```
perf-serialize-utility
```
- Use createSerializer for link URLs
```
perf-debounce-search
```
- Debounce search input before URL update

6. History & Navigation (MEDIUM)

```
history-push-navigation
```
- Use history:push for navigation-like state
```
history-replace-ephemeral
```
- Use history:replace for ephemeral state
```
history-scroll-behavior
```
- Control scroll behavior on URL changes
```
history-back-sync
```
- Handle browser back/forward navigation

7. Debugging & Testing (LOW-MEDIUM)

```
debug-enable-logging
```
- Enable debug logging for troubleshooting
```
debug-common-errors
```
- Diagnose common nuqs errors
```
debug-testing
```
- Test components with URL state

8. Advanced Patterns (LOW)

```
advanced-custom-parsers
```
- Create custom parsers for complex types
```
advanced-url-keys
```
- Use urlKeys for shorter URLs
```
advanced-eq-function
```
- Implement eq function for object parsers
```
advanced-framework-adapters
```
- Use framework-specific adapters

How to Use

Read individual reference files for detailed explanations and code examples:

Section definitions - Category structure and impact levels
Rule template - Template for adding new rules

Reference Files

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