name: nuqs description: nuqs（类型安全的URL查询状态）针对Next.js应用的最佳实践。该技能应用于编写、审查或重构使用nuqs进行URL状态管理的代码。触发条件包括涉及useQueryState、useQueryStates、搜索参数、URL状态、查询参数、nuqs解析器或带状态的Next.js路由的任务。
Next.js社区nuqs最佳实践
全面的指南，用于在Next.js应用中使用nuqs进行类型安全的URL查询状态管理。包含42条规则，覆盖8个类别，按影响优先级排序，以指导代码生成、重构和代码审查。
何时应用
参考这些指南当：
- 使用nuqs实现基于URL的状态
- 在Next.js项目中设置nuqs
- 配置URL参数的解析器
- 将URL状态与服务器组件集成
- 优化URL更新性能
- 调试与nuqs相关的问题
规则类别按优先级
| 优先级 | 类别 | 影响 | 前缀 |
|---|---|---|---|
| 1 | 解析器配置 | 关键 | parser- |
| 2 | 适配器与设置 | 关键 | setup- |
| 3 | 状态管理 | 高 | state- |
| 4 | 服务器集成 | 高 | server- |
| 5 | 性能优化 | 中 | perf- |
| 6 | 历史与导航 | 中 | history- |
| 7 | 调试与测试 | 低-中 | debug- |
| 8 | 高级模式 | 低 | advanced- |
快速参考
1. 解析器配置（关键）
parser-use-typed-parsers- 为非字符串值使用类型化解析器parser-with-default- 为非空状态使用withDefaultparser-enum-validation- 使用枚举解析器用于受约束的值parser-array-format- 选择正确的数组解析器格式parser-json-validation- 验证JSON解析器输入parser-date-format- 选择适当的日期解析器parser-index-offset- 使用parseAsIndex用于1-based URL显示parser-hex-colors- 使用parseAsHex用于颜色值
2. 适配器与设置（关键）
setup-nuqs-adapter- 用NuqsAdapter包装应用setup-use-client- 为钩子添加’use client’指令setup-import-server- 从nuqs/server导入服务器实用程序setup-nextjs-version- 确保兼容的Next.js版本setup-shared-parsers- 在专用文件中定义共享解析器
3. 状态管理（高）
state-use-query-states- 使用useQueryStates用于相关参数state-functional-updates- 使用函数式更新用于派生状态state-clear-with-null- 使用null清除URL参数state-controlled-inputs- 正确处理受控输入值state-avoid-derived- 避免从URL参数派生状态state-options-inheritance- 使用withOptions用于解析器级配置state-setter-return- 使用设置器返回值用于URL访问
4. 服务器集成（高）
server-search-params-cache- 使用createSearchParamsCache用于服务器组件server-shallow-false- 使用shallow:false以触发服务器重新渲染server-use-transition- 集成useTransition用于加载状态server-parse-before-get- 在服务器组件中调用parse()再调用get()server-share-parsers- 在客户端和服务器间共享解析器server-next15-async- 处理Next.js 15+中的异步searchParams
5. 性能优化（中）
perf-throttle-updates- 限制快速URL更新perf-clear-on-default- 使用clearOnDefault用于干净URLperf-avoid-rerender- 记忆化使用URL状态的组件perf-serialize-utility- 使用createSerializer用于链接URLperf-debounce-search- 在URL更新前防抖搜索输入
6. 历史与导航（中）
history-push-navigation- 使用history:push用于类似导航的状态history-replace-ephemeral- 使用history:replace用于短暂状态history-scroll-behavior- 控制URL变化时的滚动行为history-back-sync- 处理浏览器后退/前进导航
7. 调试与测试（低-中）
debug-enable-logging- 启用调试日志用于故障排除debug-common-errors- 诊断常见nuqs错误debug-testing- 测试具有URL状态的组件
8. 高级模式（低）
advanced-custom-parsers- 为复杂类型创建自定义解析器advanced-url-keys- 使用urlKeys用于更短URLadvanced-eq-function- 为对象解析器实现eq函数advanced-framework-adapters- 使用框架特定适配器
如何使用
阅读各个参考文件以获取详细解释和代码示例：
- Section definitions - 类别结构和影响级别
- Rule template - 添加新规则的模板
参考文件
| 文件 | 描述 |
|---|---|
| AGENTS.md | 包含所有规则的完整编译指南 |
| references/_sections.md | 类别定义和排序 |
| assets/templates/_template.md | 新规则的模板 |
| metadata.json | 版本和参考信息 |