nuqs

Original：🇺🇸 English

Translated

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.

6installs

Sourcefellipeutaka/leon

Added on2026-07-27

NPX Install

npx skill4agent add fellipeutaka/leon nuqs

SKILL.md Content

View Translation Comparison →

nuqs Best Practices

Type-safe URL query state management with nuqs 2.x. Contains rules across 8 categories, prioritized by impact.

Rule Categories


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	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
```
— Use typed parsers for non-string values
```
parser-with-default
```
— Use withDefault for non-nullable state
```
parser-enum-literals
```
— Use literal/enum parsers for constrained values
```
parser-array-format
```
— Choose correct array parser format
```
parser-json-validation
```
— Validate JSON parser with Standard Schema
```
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
```
parser-custom
```
— Create custom parsers for complex types

2. Adapter & Setup (CRITICAL)

```
setup-adapter
```
— Wrap app with correct NuqsAdapter
```
setup-client-hooks
```
— Add 'use client' for hooks
```
setup-server-imports
```
— Import server utilities from nuqs/server
```
setup-shared-parsers
```
— Define shared parsers in a 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 config
```
state-setter-return
```
— Use setter return value for URL access

4. Server Integration (HIGH)

```
server-create-loader
```
— Use createLoader for page-level server parsing
```
server-search-params-cache
```
— Use createSearchParamsCache for nested RSC access
```
server-shallow-false
```
— Use shallow:false to trigger server re-renders
```
server-use-transition
```
— Integrate useTransition for loading states
```
server-share-parsers
```
— Share parsers between client and server
```
server-next15-async
```
— Handle async searchParams in Next.js 15+

5. Performance (MEDIUM)

```
perf-limit-url-updates
```
— Throttle/debounce 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

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 and hooks with URL state

8. Advanced Patterns (LOW)

```
advanced-url-keys
```
— Use urlKeys for shorter URL param names
```
advanced-eq-function
```
— Implement eq function for object parsers
```
advanced-adapter-props
```
— Configure NuqsAdapter global defaults and URL middleware
```
advanced-standard-schema
```
— Use createStandardSchemaV1 and inferParserType
```
advanced-optimistic-search-params
```
— useOptimisticSearchParams for Remix/React Router