nuqs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

nuqs Best Practices

nuqs 最佳实践

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

基于nuqs 2.x的类型安全URL查询状态管理，包含8个类别的规则，按影响优先级排序。

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


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

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

Quick Reference

快速参考

1. Parser Configuration (CRITICAL)

1. 解析器配置（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

```
parser-typed
```
— 对非字符串值使用类型化解析器
```
parser-with-default
```
— 为非空状态使用withDefault
```
parser-enum-literals
```
— 对受限值使用字面量/枚举解析器
```
parser-array-format
```
— 选择正确的数组解析器格式
```
parser-json-validation
```
— 使用标准 Schema 验证JSON解析器
```
parser-date-format
```
— 选择合适的日期解析器
```
parser-index-offset
```
— 使用parseAsIndex实现基于1的URL显示
```
parser-hex-colors
```
— 对颜色值使用parseAsHex
```
parser-custom
```
— 为复杂类型创建自定义解析器

2. Adapter & Setup (CRITICAL)

2. 适配器与设置（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

```
setup-adapter
```
— 使用正确的NuqsAdapter包裹应用
```
setup-client-hooks
```
— 为钩子添加'use client'指令
```
setup-server-imports
```
— 从nuqs/server导入服务器工具
```
setup-shared-parsers
```
— 在专用文件中定义共享解析器

3. State Management (HIGH)

3. 状态管理（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

```
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
```
— 使用setter返回值访问URL

4. Server Integration (HIGH)

4. 服务器集成（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+

```
server-create-loader
```
— 对页面级服务器解析使用createLoader
```
server-search-params-cache
```
— 对嵌套RSC访问使用createSearchParamsCache
```
server-shallow-false
```
— 使用shallow:false触发服务器重新渲染
```
server-use-transition
```
— 集成useTransition处理加载状态
```
server-share-parsers
```
— 在客户端与服务器之间共享解析器
```
server-next15-async
```
— 在Next.js 15+中处理异步searchParams

5. Performance (MEDIUM)

5. 性能优化（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

```
perf-limit-url-updates
```
— 对URL更新进行节流/防抖
```
perf-clear-on-default
```
— 使用clearOnDefault实现简洁URL
```
perf-avoid-rerender
```
— 对使用URL状态的组件进行 memoize
```
perf-serialize-utility
```
— 对链接URL使用createSerializer

6. History & Navigation (MEDIUM)

6. 历史记录与导航（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

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

7. Debugging & Testing (LOW-MEDIUM)

7. 调试与测试（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

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

8. Advanced Patterns (LOW)

8. 高级模式（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

```
advanced-url-keys
```
— 使用urlKeys缩短URL参数名称
```
advanced-eq-function
```
— 为对象解析器实现eq函数
```
advanced-adapter-props
```
— 配置NuqsAdapter全局默认值与URL中间件
```
advanced-standard-schema
```
— 使用createStandardSchemaV1和inferParserType
```
advanced-optimistic-search-params
```
— 在Remix/React Router中使用useOptimisticSearchParams