跳至正文
OpenAgentSkill
浏览已开放 · 目录记录日期 2026-11-21 · 自动更新和账户服务暂时关闭。
开发与测试

nuqs

nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.

pproenca · 已有 AI 审核记录

安装与使用

运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。

npx skills add pproenca/dot-skills --skill nuqs

技能说明


name: nuqs description: nuqs (type-safe URL query state) best practices for Next.js and other React frameworks. This skill should be used when writing, reviewing, or refactoring code that uses nuqs for URL state management. Triggers on tasks involving useQueryState, useQueryStates, search params, URL state, query parameters, nuqs parsers, limitUrlUpdates, Standard Schema, NuqsAdapter, or Next.js routing with state.

Community nuqs Best Practices for Next.js & React

Comprehensive guide for type-safe URL query state management with nuqs across Next.js, React Router, TanStack Router, Remix, and plain React. Covers nuqs v2.5–v2.9 features. Contains 39 rules across 8 categories, prioritized by impact to guide code generation, refactoring, and code review.

When to Apply

Reference these guidelines when:

  • Implementing URL-based state with nuqs
  • Setting up nuqs in a Next.js or React Router project
  • Configuring parsers for URL parameters
  • Integrating URL state with Server Components
  • Optimizing URL update performance (limitUrlUpdates, key isolation)
  • Sharing parser definitions with tRPC / TanStack Router / forms via Standard Schema
  • Debugging nuqs-related issues

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Parser ConfigurationCRITICALparser-
2Adapter & SetupCRITICALsetup-
3State ManagementHIGHstate-
4Server IntegrationHIGHserver-
5Performance OptimizationMEDIUMperf-
6History & NavigationMEDIUMhistory-
7Debugging & TestingLOW-MEDIUMdebug-
8Advanced PatternsLOWadvanced-

Quick Reference

1. Parser Configuration (CRITICAL)

  • 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

2. Adapter & Setup (CRITICAL)

  • 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-default-options — Configure app-wide defaults on NuqsAdapter (v2.5+)

3. State Management (HIGH)

  • state-use-query-states — Use useQueryStates for related parameters
  • state-clear-with-null — Clear URL parameters with null
  • 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-standard-schema — Use Standard Schema for cross-library validation (v2.5+)

4. Server Integration (HIGH)

  • server-search-params-cache — Use createSearchParamsCache (or createLoader) 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-next15-async — Handle async searchParams in Next.js 15+

5. Performance Optimization (MEDIUM)

  • perf-throttle-updates — Throttle rapid URL updates with limitUrlUpdates
  • perf-debounce-search — Debounce search input with built-in limitUrlUpdates
  • perf-clear-on-default — Use clearOnDefault for clean URLs
  • perf-avoid-rerender — Memoize components using URL state (Next.js)
  • perf-key-isolation — Rely on key isolation outside Next.js (v2.5+)
  • perf-serialize-utility — Use createSerializer for link URLs

6. History & Navigation (MEDIUM)

  • history-push-navigation — Choose history:push vs history:replace
  • history-scroll-behavior — Control scroll behavior on URL changes

7. Debugging & Testing (LOW-MEDIUM)

  • debug-enable-logging — Enable debug logging for troubleshooting
  • debug-testing — Test components with URL state

8. Advanced Patterns (LOW)

  • 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](refe
阅读完整来源 ↗