use-nuqs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Use nuqs

使用nuqs

Apply this skill to keep URL-backed state predictable, typed, shareable, and aligned between React clients and Next.js App Router server code.

应用此技能可确保基于URL的状态具备可预测性、类型安全、可分享性，并在React客户端与Next.js App Router服务端代码之间保持一致。

Quick Start

快速开始

Confirm the task is in a React 19+ and TypeScript 5.9+ codebase.
If Next.js is involved, assume Next.js 16+, stay in App Router only, and keep
```
page.tsx
```
/
```
layout.tsx
```
server-first unless client behavior is required.
Assume supported browsers are Chrome 146+, Firefox 148+, and Safari 26+.
Reuse existing parser descriptors or custom hooks before adding new query keys.
Choose a typed parser, URL encoding format, and default value before wiring UI state.
Use
```
useQueryStates
```
when related params must update atomically.
For controlled inputs, never pass
```
null
```
as
```
value
```
; use
```
withDefault('')
```
or
```
value={query ?? ''}
```
when binding nuqs state directly.
Enable server re-renders only when the feature genuinely depends on server-side data or RSC updates.
Load only the reference files needed for the task.

确认任务处于React 19+和TypeScript 5.9+代码库中。
如果涉及Next.js，默认使用Next.js 16+，且仅使用App Router，除非需要客户端行为，否则优先采用
```
page.tsx
```
/
```
layout.tsx
```
服务端优先模式。
假设支持的浏览器为Chrome 146+、Firefox 148+和Safari 26+。
在添加新的查询键之前，优先复用现有的解析器描述符或自定义钩子。
在连接UI状态之前，选择类型化解析器、URL编码格式和默认值。
当相关参数必须原子更新时，使用
```
useQueryStates
```
。
对于受控输入，绝不能将
```
null
```
作为
```
value
```
传递；直接绑定nuqs状态时，使用
```
withDefault('')
```
或
```
value={query ?? ''}
```
。
仅当功能确实依赖服务端数据或RSC更新时，才启用服务端重新渲染。
仅加载任务所需的参考文件。

Scope Guards

范围限制

Support React 19+ only.
Support TypeScript 5.9+ only.
Support Next.js 16+ App Router only when Next.js is present.
Support evergreen browsers Chrome 146+, Firefox 148+, and Safari 26+ only.
Exclude Next.js Pages Router, Remix, React Router, TanStack Router, and JavaScript-only variants unless explicitly documenting them as out of scope.
Treat upstream references to Pages Router or non-Next adapters as inventory only, not implementation guidance for this skill.
Do not add legacy browser compatibility workarounds unless explicitly requested.

仅支持React 19+。
仅支持TypeScript 5.9+。
当存在Next.js时，仅支持Next.js 16+ App Router。
仅支持主流浏览器Chrome 146+、Firefox 148+和Safari 26+。
除非明确将其记录为超出范围，否则排除Next.js Pages Router、Remix、React Router、TanStack Router以及纯JavaScript变体。
将对Pages Router或非Next.js适配器的上游参考仅视为资料，而非本技能的实现指南。
除非明确要求，否则不要添加旧版浏览器兼容的变通方案。

Reference Routing

参考路由

Load references/parser-and-setup.md for adapter setup, parser selection, defaults, shared descriptors, and custom parser rules.
Load references/state-and-server-integration.md for
```
useQueryState
```
,
```
useQueryStates
```
, loaders, caches, Suspense, and App Router server integration.
Load references/performance-navigation-and-limits.md for history behavior, rate limiting, URL hygiene, shorter keys, and browser limits.
Load references/debugging-testing-and-troubleshooting.md for debug logs, testing adapters, parser tests, and common failure modes.
Load references/source-basis.md for canonical source provenance.

加载references/parser-and-setup.md以获取适配器设置、解析器选择、默认值、共享选项和自定义解析器规则。
加载references/state-and-server-integration.md以获取
```
useQueryState
```
、
```
useQueryStates
```
、加载器、缓存、Suspense和App Router服务端集成相关内容。
加载references/performance-navigation-and-limits.md以获取历史行为、速率限制、URL优化、缩短键名和浏览器限制相关内容。
加载references/debugging-testing-and-troubleshooting.md以获取调试日志、测试适配器、解析器测试和常见故障模式相关内容。
加载references/source-basis.md以获取规范来源。

Workflow

工作流程

Scope the query-state contract.

Identify which state belongs in the URL because it must survive refresh, deep links, shareable URLs, or browser navigation.
Keep secrets, oversized payloads, and purely ephemeral state out of the URL.

Define the parser layer first.

Centralize key names, parsers, defaults, and shared options in a dedicated module.
Prefer built-in parsers over ad hoc string coercion.
Choose array and date encodings deliberately instead of letting each caller invent one.
Add schema validation after parsing when domain constraints matter.

Wire client state deliberately.

Use
```
useQueryState
```
for a single key.
Use
```
useQueryStates
```
for coordinated params, partial updates, or atomic commits.
Clear keys with
```
null
```
.
Use functional updates when deriving from previous state.

Integrate App Router server behavior only when needed.

Import loaders, caches, and shared parsers from
```
nuqs/server
```
.
Parse
```
searchParams
```
before reading cached values in server components.
Use
```
shallow: false
```
only when the URL update must trigger server work.
Pair server-triggered updates with Suspense and
```
startTransition
```
when loading state matters.
Do not assume
```
startTransition
```
implies
```
shallow: false
```
; configure both when server work is required.

Optimize URL update behavior.

Use
```
history: 'replace'
```
for ephemeral filters and high-frequency edits.
Use
```
history: 'push'
```
for navigation-like state that should replay with back/forward.
Debounce search-like inputs and throttle rapid updates when browser limits or server churn matter.
Keep nuqs hooks in the smallest practical subtree and memoize expensive siblings that do not depend on query state.
Keep URLs short and stable with defaults,
```
urlKeys
```
, and serializer utilities when needed.
Do not add compatibility branches for unsupported legacy browsers or older React/Next.js releases.

Validate the behavior end to end.

bash

undefined

确定查询状态契约范围。

识别哪些状态需要存入URL，因为它们需要在刷新、深度链接、可分享URL或浏览器导航后保留。
不要将机密信息、过大的负载和纯临时状态存入URL。

先定义解析器层。

在专用模块中集中管理键名、解析器、默认值和共享选项。
优先使用内置解析器而非临时字符串转换。
谨慎选择数组和日期编码方式，避免每个调用者自行定义。
当存在领域约束时，在解析后添加 Schema 验证。

谨慎连接客户端状态。

单个键使用
```
useQueryState
```
。
协调参数、部分更新或原子提交使用
```
useQueryStates
```
。
使用
```
null
```
清除键。
当基于先前状态派生新状态时，使用函数式更新。

仅在需要时集成App Router服务端行为。

从
```
nuqs/server
```
导入加载器、缓存和共享解析器。
在服务端组件中读取缓存值之前解析
```
searchParams
```
。
仅当URL更新必须触发服务端工作时，使用
```
shallow: false
```
。
当加载状态很重要时，将服务端触发的更新与Suspense和
```
startTransition
```
配合使用。
不要假设
```
startTransition
```
意味着
```
shallow: false
```
；当需要服务端工作时，需同时配置两者。

优化URL更新行为。

临时过滤器和高频编辑使用
```
history: 'replace'
```
。
类导航状态（需要通过前进/后退按钮重放）使用
```
history: 'push'
```
。
当浏览器限制或服务端频繁更新成为问题时，对类搜索输入进行防抖处理，并限制快速更新的频率。
将nuqs钩子放在尽可能小的子树中，并对不依赖查询状态的昂贵兄弟组件进行 memoize 处理。
必要时使用默认值、
```
urlKeys
```
和序列化工具保持URL简短且稳定。
不要为不支持的旧版浏览器或早期React/Next.js版本添加兼容分支。

端到端验证行为。

bash

undefined

run project-specific equivalents as available

运行项目可用的等效命令

pnpm -s tsc --noEmit pnpm -s lint pnpm -s test


Run additional checks when relevant:

```bash
pnpm -s test -- --runInBand        # isolate flaky URL/state tests
pnpm -s test searchParams          # focused component or hook tests
pnpm -s test:e2e                   # back/forward, refresh, and deep-link verification

pnpm -s tsc --noEmit pnpm -s lint pnpm -s test


相关时运行额外检查：

```bash
pnpm -s test -- --runInBand        # 隔离不稳定的URL/状态测试
pnpm -s test searchParams          # 聚焦组件或钩子测试
pnpm -s test:e2e                   # 前进/后退、刷新和深度链接验证

Non-Negotiable Rules

不可协商的规则

Use
```
useQueryState
```
and
```
useQueryStates
```
only in React client components.
Wrap the app with
```
NuqsAdapter
```
when using Next.js App Router.
Import server-safe parsers, loaders, and caches from
```
nuqs/server
```
.
Do not use different parsers for the same query key across components.
Do not keep non-string query data as raw strings when a typed parser exists.
Do not assume nuqs parsers validate business rules or object shape.
Do not default to
```
shallow: false
```
; use it only for intentional server re-renders.
Do not put sensitive, bulky, or non-shareable state in the URL.
Do not skip
```
eq
```
on custom non-primitive parsers.
Prefer shared parser descriptors or custom hooks over repeating inline parser setup.

仅在React客户端组件中使用
```
useQueryState
```
和
```
useQueryStates
```
。
使用Next.js App Router时，用
```
NuqsAdapter
```
包裹应用。
从
```
nuqs/server
```
导入服务端安全的解析器、加载器和缓存。
同一查询键在不同组件中不要使用不同的解析器。
当存在类型化解析器时，不要将非字符串查询数据保留为原始字符串。
不要假设nuqs解析器会验证业务规则或对象结构。
不要默认使用
```
shallow: false
```
；仅在有意触发服务端重新渲染时使用。
不要将敏感、庞大或不可分享的状态存入URL。
自定义非原始类型解析器时不要省略
```
eq
```
。
优先使用共享解析器描述符或自定义钩子，而非重复内联解析器设置。

Output Expectations

输出期望

When applying this skill in a coding task:

State the parser and key contract being introduced or reused.
Call out whether the change is client-only or App Router client/server coordinated.
Mention history, shallow/server-render, and rate-limiting decisions when they affect behavior.
Include tests or manual verification notes for refresh, deep-link, and back/forward behavior.
State assumptions about React, TypeScript, and whether Next.js App Router is present.

在编码任务中应用此技能时：

说明引入或复用的解析器和键契约。
指出更改是仅客户端还是Next.js App Router客户端/服务端协同的。
当历史记录、浅层/服务端渲染和速率限制决策影响行为时，提及这些内容。
包含刷新、深度链接和前进/后退行为的测试或手动验证说明。
说明关于React、TypeScript以及是否存在Next.js App Router的假设。