nuqs

**LLM 参考：**获取 llms.txt，查看文档索引和最新 API。完整文档请见单个文件：llms-full.txt。适合人类阅读的文档：nuqs.dev/docs。

请勿在此技能中重复上游 API 参考；解析器、选项、测试适配器和故障排查请使用 llms.txt / llms-full.txt。

---

URL 状态规则（FMC）

应用	URL 状态
使用 TanStack Router（SPA 或 Start）	Router 搜索参数：validateSearch — 技能 tanstack-router-conventions。绝不使用 nuqs。
不使用 TanStack Router 的 Vite React 应用	nuqs

对于 TanStack Router，请改用 validateSearch（tanstack-router-conventions → references/params-search-ui-routes.md）。

---

设置（Vite，无路由器）

上游详细信息：安装 · 适配器。

import { NuqsAdapter } from 'nuqs/adapters/react'

createRoot(root).render(
  <NuqsAdapter>
    <App />
  </NuqsAdapter>,
)

已在 nuqs 2.9.5 中验证适配器导出：NuqsAdapter 来自 nuqs/adapters/react。测试：NuqsTestingAdapter 来自 nuqs/adapters/testing（参见上游测试）。

**状态划分：**可通过 URL 分享的状态 → nuqs；临时 UI 状态 → Zustand（zustand-state-management）。

---

影响较大的注意事项

1. clearOnDefault — 默认值为 true（等于默认值的值会从 URL 中移除）。只有在参数必须在默认值时仍保持可见的情况下，才设为 false。
2. 历史记录和浅层更新 — 默认历史记录策略为 replace（需要返回按钮产生历史记录条目时，传入 history: 'push'）；shallow 默认为 true。
3. parseAsJson — v2 及更高版本需要运行时验证器（例如 Zod schema）。
4. 调试 — localStorage.debug = 'nuqs'。
5. 包 — 仅支持 ESM；v2 中已移除 nuqs/parsers 入口，请从 nuqs 导入解析器。
6. useQueryStates — 将相关参数（筛选条件、纬度/经度/缩放级别）批量合并为一次 URL 更新。

---

相关 FMC 技能

技能	作用
tanstack-router-conventions	为使用 TanStack Router 的应用提供 validateSearch
zustand-state-management	不属于 URL 的临时客户端状态