Skip to content
OpenAgentSkill
Browsing is open · Catalog captured 2026-11-21 · Automatic updates and account services are paused.
Development

nuqs-scaffolder

Scaffolds URL-state filters for a Next.js page — typed `searchParams.ts` parser map and a `<Filters />` client component backed by `useQueryStates`. From a single JSON spec, generates four files in lockstep — client parser map, server loader/cache/serializer, client component, and Vitest test — all sharing the same parser definitions per the nuqs Standard Schema pattern. Trigger even when the user only says "add filters to /search" or "I need a typed query string for this page" — both are exactly this skill's job.

pproenca · AI review on file

Installation

Read the source and dependencies before running a command. Copying does not install or execute anything.

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

About this skill


name: nuqs-scaffolder description: Scaffolds URL-state filters for a Next.js page — typed searchParams.ts parser map and a <Filters /> client component backed by useQueryStates. From a single JSON spec, generates four files in lockstep — client parser map, server loader/cache/serializer, client component, and Vitest test — all sharing the same parser definitions per the nuqs Standard Schema pattern. Trigger even when the user only says "add filters to /search" or "I need a typed query string for this page" — both are exactly this skill's job.

nuqs Scaffolder

Generate a coherent set of nuqs files from one spec. The skill is template-driven — you read the spec, copy the templates, and substitute placeholders. No build step, no codegen runtime; the templates ARE the artifact.

When to Apply

Use this skill when:

  • A new Next.js page needs URL-backed filters, pagination, search, or sort state
  • You're standardising an existing page's ad-hoc useState filters onto nuqs
  • A code review keeps catching client/server drift in parser definitions — this skill makes drift mechanically impossible because both sides import the same map
  • A user asks to "add Standard Schema validation to these query params for tRPC" — the generated searchParams.server.ts already exports the schema

If the codebase has legacy nuqs patterns instead, run the nuqs-codemod-runner skill first.

How to Use

  1. Read or create a spec. Start from assets/templates/spec.template.json and fill in name, module, and params. See "Spec Format" below.
  2. Render each template by replacing placeholders with values derived from the spec.
  3. Write each rendered file to the path computed from config.json (overridable per-call).
  4. Show the user the diff before committing — this skill never modifies existing files; if a target path exists, ask before overwriting.

The agent does the rendering — Claude is the templating engine. Each template is annotated with markers (/*= ... =*/) that name the placeholder slot and document the substitution rule.

Spec Format

{
  "name":   "Search",                    // PascalCase — drives the exported symbol names
  "module": "search",                    // kebab-case — drives file paths and the "module" folder

  "params": {
    "q":          { "type": "string",                                    "default": "" },
    "page":       { "type": "integer",                                   "default": 1 },
    "limit":      { "type": "integer",                                   "default": 10 },
    "categories": { "type": "array-of-string-native",                    "default": [] },
    "sort":       { "type": "string-literal", "values": ["asc","desc"],  "default": "asc" },
    "minPrice":   { "type": "float",                                     "default": null },
    "lastSeen":   { "type": "iso-date",                                  "default": null }
  }
}

Supported type values

typeParser usedNotes
stringparseAsString
integerparseAsInteger
floatparseAsFloat
booleanparseAsBoolean
iso-dateparseAsIsoDateDate-only
iso-date-timeparseAsIsoDateTimeDate + time
timestampparseAsTimestampms since epoch
hexparseAsHexNumeric value, hex URL form
indexparseAsIndex0-based in code, 1-based in URL
array-of-stringparseAsArrayOf(parseAsString)?tags=a,b,c
array-of-string-nativeparseAsNativeArrayOf(parseAsString)?tag=a&tag=b — requires nuqs ≥ 2.7
string-literalparseAsStringLiteral(values)Requires values: string[]
number-literalparseAsNumberLiteral(values)Requires values: number[]
jsonparseAsJson(SchemaName.parse)Generates a Zod schema stub; mark default separately

If default is null, the param is nullable; otherwise the template uses .withDefault(...).

Available Templates

TemplateRenders to (default)Loaded when
searchParams.ts.templatelib/{module}-search-params.tsAlways
searchParams.server.ts.templatelib/{module}-search-params.server.tsAlways
filters.tsx.templatecomponents/{module}/{name}-filters.tsxAlways
filters.test.tsx.templatecomponents/{module}/{name}-filters.test.tsxIf config.generate_tests is true
spec.json.templateAnywhere — starter for the userFirst-run prompt

Template files end in .template so editors don't apply syntax highlighting to placeholder markers — the original extension is preserved as the suffix-before-.template so you can still tell at a glance what the rendered file will be.

Paths are configurable in config.json — override globs, file naming style (kebab vs PascalCase), and whether tests are emitted.

Placeholder Reference

All templates use the same placeholder syntax. The agent substitutes them in one pass:

PlaceholderSourceExample
__NAME__spec.nameSearch
__name__camelCase form of spec.namesearch
__module__spec.modulesearch
/*= PARSERS =*/Iterate spec.params → key: parseAsXxx.withDefault(...) linessee template
/*= COMPONENT_FIELDS =*/Iterate spec.params → one input/select per typesee template
/*= TEST_CASES =*/Iterate spec.params → one assertion per defaultsee template
/*= NULLABLE_IMPORTS =*/Add Nullable helper import if any param is nullableconditional
/*= ZOD_SCHEMAS =*/For json type params, emit a Zod schema stubconditio
Read the complete source ↗