nuqs-codemod-runner

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 nuqs version bump in package.json from <2.5 to >=2.5 is part of the diff
• The user has just installed/updated the nuqs skill 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

1. scripts/scan.sh <repo-root> — ripgreps every .ts/.tsx/.js/.jsx file for the 5 legacy patterns, emits scan.json with {path, line, matchedPattern, snippet, suggestion}.
2. scripts/report.sh — renders scan.json as 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.
3. scripts/apply.sh [--filter <codemod-id>] — runs the jscodeshift transforms in scripts/transforms/. Refuses to run unless a fresh scan.json exists for the current git HEAD and the working tree is clean (--allow-dirty overrides).
4. scripts/verify.sh — runs tsc --noEmit and npm run lint (or the equivalent commands from config.json). If anything fails, git restore reverts 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.sh aborts if the working tree is dirty (use git stash first, or pass --allow-dirty after reading gotchas.md)
• apply.sh aborts if scan.json is older than 60 minutes or was generated against a different git HEAD — re-run scan.sh
• The hooks/hooks.json PreToolUse matcher blocks any direct node scripts/transforms/*.js invocation that bypasses the orchestrator
• verify.sh auto-reverts on TS or lint failure via git restore over the touched files (recorded in last-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.