pproenca nuqs Codemod Runner
Migrate a codebase from pre-v2.5 nuqs patterns to current v2.5–v2.8 idioms. The skill is read-only by default — it never modifies files without an explicit confirmation step, and refuses to run on a dirty git working tree.
When to Apply
Trigger this skill when:
- A user asks to "upgrade nuqs" or "migrate to nuqs 2.x" in a project that already uses nuqs
- You spot any of the 5 legacy patterns during a review (see the codemod table below)
- A
nuqsversion bump inpackage.jsonfrom<2.5to>=2.5is part of the diff - The user has just installed/updated the
nuqsskill and wants to bring existing code into line with it
This skill is the automation companion to skills/.curated/nuqs/ — that skill teaches what each correct pattern looks like; this skill rewrites legacy code to match.
Workflow Overview
┌──────────┐ ┌────────────┐ ┌──────────────────┐ ┌───────────┐ ┌────────────┐
│ scan.sh │──▶ │ scan.json │──▶ │ report.sh │──▶ │ apply.sh │──▶ │ verify.sh │
└──────────┘ └────────────┘ │ (dry-run table) │ │ (codemods)│ │ (tsc+lint) │
└──────────────────┘ └───────────┘ └────────────┘
│ ▲ │
▼ │ ▼
user reviews ──────────── confirms on fail: revert
scripts/scan.sh <repo-root>— ripgreps every.ts/.tsx/.js/.jsxfile for the 5 legacy patterns, emitsscan.jsonwith{path, line, matchedPattern, snippet, suggestion}.scripts/report.sh— rendersscan.jsonas a markdown table grouped by codemod, with file paths and before/after pairs. Show this output to the user verbatim and ask for explicit confirmation before continuing.scripts/apply.sh [--filter <codemod-id>]— runs the jscodeshift transforms inscripts/transforms/. Refuses to run unless a freshscan.jsonexists for the currentgit HEADand the working tree is clean (--allow-dirtyoverrides).scripts/verify.sh— runstsc --noEmitandnpm run lint(or the equivalent commands fromconfig.json). If anything fails,git restorereverts every file the codemod touched.
Run all four sequentially. If the user only wants to scan, stop at step 2.
The Five Codemods
| ID | Detects | Rewrites to |
|---|---|---|
throttle-ms |
withOptions({ throttleMs: N }) or setX(v, { throttleMs: N }) |
withOptions({ limitUrlUpdates: throttle(N) }) + adds throttle to the nuqs import |
manual-debounce |
useState mirror + useEffect + setTimeout debounce around a useQueryState setter |
withOptions({ limitUrlUpdates: debounce(N) }) + adds debounce to the nuqs import; deletes the mirror state and effect |
unchecked-json-cast |
parseAsJson<T>() (no validator) or parseAsJson((v) => v as T) |
Inserts a // TODO: validate type-guard stub or, if Zod is detected in package.json, a parseAsJson(SchemaName.parse) form |
react-router-unversioned |
from 'nuqs/adapters/react-router' |
from 'nuqs/adapters/react-router/v6' (the alias the unversioned import historically pointed at) |
parser-builder-type |
type references to ParserBuilder<T> from nuqs |
SingleParserBuilder<T> |
See references/workflow.md for the exact AST shapes each codemod matches and the edge cases it deliberately skips.
Setup
On first run, config.json is populated with the user's lint/typecheck commands and a default min_node_version. See _setup_instructions in config.json for what to fill in.
Risk & Guardrails
This skill is write-risk (it modifies source files). Guardrails:
apply.shaborts if the working tree is dirty (usegit stashfirst, or pass--allow-dirtyafter readinggotchas.md)apply.shaborts ifscan.jsonis older than 60 minutes or was generated against a differentgit HEAD— re-runscan.sh- The
hooks/hooks.jsonPreToolUse matcher blocks any directnode scripts/transforms/*.jsinvocation that bypasses the orchestrator verify.shauto-reverts on TS or lint failure viagit restoreover the touched files (recorded inlast-run.json)
Related Skills
nuqs— Best-practice reference for nuqs v2.5+. This skill rewrites legacy code; that skill defines the target.
Gotchas
See gotchas.md for failure modes discovered during use.