nuqs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Community nuqs Best Practices for Next.js

社区版 nuqs 在 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.

本指南全面介绍了在Next.js应用中使用nuqs进行类型安全的URL查询状态管理的方法。包含8个类别下的42条规则，按影响级别排序，可指导代码生成、重构和代码评审工作。

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

在以下场景中可参考本指南：

使用nuqs实现基于URL的状态管理
在Next.js项目中配置nuqs
为URL参数配置解析器
将URL状态与Server Components集成
优化URL更新性能
调试与nuqs相关的问题

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-`


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

优先级	类别	影响级别	前缀
1	解析器配置	关键	`parser-`
2	适配器与设置	关键	`setup-`
3	状态管理	高	`state-`
4	服务端集成	高	`server-`
5	性能优化	中	`perf-`
6	历史记录与导航	中	`history-`
7	调试与测试	低-中	`debug-`
8	高级模式	低	`advanced-`

Quick Reference

快速参考

1. Parser Configuration (CRITICAL)

1. 解析器配置（关键）

```
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

```
parser-use-typed-parsers
```
- 为非字符串值使用类型化解析器
```
parser-with-default
```
- 为非空状态使用withDefault
```
parser-enum-validation
```
- 为受限值使用枚举解析器
```
parser-array-format
```
- 选择正确的数组解析器格式
```
parser-json-validation
```
- 验证JSON解析器的输入
```
parser-date-format
```
- 选择合适的日期解析器
```
parser-index-offset
```
- 使用parseAsIndex实现基于1的URL显示
```
parser-hex-colors
```
- 为颜色值使用parseAsHex

2. Adapter & Setup (CRITICAL)

2. 适配器与设置（关键）

```
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

```
setup-nuqs-adapter
```
- 使用NuqsAdapter包裹应用
```
setup-use-client
```
- 为钩子添加'use client'指令
```
setup-import-server
```
- 从nuqs/server导入服务端工具
```
setup-nextjs-version
```
- 确保使用兼容的Next.js版本
```
setup-shared-parsers
```
- 在专用文件中定义共享解析器

3. State Management (HIGH)

3. 状态管理（高）

```
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

```
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 Integration (HIGH)

4. 服务端集成（高）

```
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+

```
server-search-params-cache
```
- 为Server Components使用createSearchParamsCache
```
server-shallow-false
```
- 使用shallow:false触发服务端重渲染
```
server-use-transition
```
- 集成useTransition处理加载状态
```
server-parse-before-get
```
- 在Server Components中先调用parse()再调用get()
```
server-share-parsers
```
- 在客户端与服务端之间共享解析器
```
server-next15-async
```
- 在Next.js 15+中处理异步searchParams

5. Performance Optimization (MEDIUM)

5. 性能优化（中）

```
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

```
perf-throttle-updates
```
- 限制频繁的URL更新
```
perf-clear-on-default
```
- 使用clearOnDefault保持URL简洁
```
perf-avoid-rerender
```
- 对使用URL状态的组件进行记忆化处理
```
perf-serialize-utility
```
- 使用createSerializer生成链接URL
```
perf-debounce-search
```
- 在更新URL前对搜索输入进行防抖处理

6. History & Navigation (MEDIUM)

6. 历史记录与导航（中）

```
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

```
history-push-navigation
```
- 对类导航状态使用history:push
```
history-replace-ephemeral
```
- 对临时状态使用history:replace
```
history-scroll-behavior
```
- 控制URL变化时的滚动行为
```
history-back-sync
```
- 处理浏览器前进/后退导航

7. Debugging & Testing (LOW-MEDIUM)

7. 调试与测试（低-中）

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

```
debug-enable-logging
```
- 启用调试日志以排查问题
```
debug-common-errors
```
- 诊断常见的nuqs错误
```
debug-testing
```
- 测试包含URL状态的组件

8. Advanced Patterns (LOW)

8. 高级模式（低）

```
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

```
advanced-custom-parsers
```
- 为复杂类型创建自定义解析器
```
advanced-url-keys
```
- 使用urlKeys缩短URL
```
advanced-eq-function
```
- 为对象解析器实现eq函数
```
advanced-framework-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

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义和排序规则
assets/templates/_template.md	新规则的模板
metadata.json	版本和参考信息