nuqs-codemod-runner — скилл для Claude Code: установка
Скилл nuqs-codemod-runner находит устаревшие паттерны nuqs версий до 2.5, показывает сухой отчёт изменений и безопасно переписывает код с проверкой типов и линтером.
MIT 142 установок ★ 227 обновлён 2026-08-15
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-codeЧто делает nuqs-codemod-runner
Инструмент автоматизирует переезд проектов на актуальные версии nuqs от 2.5 до 2.8. Скрипт scripts/scan.sh ищет пять устаревших шаблонов: устаревший параметр throttleMs, ручные связки useState и setTimeout для дебаунса вокруг useQueryState, небезопасные касты parseAsJson, версии без указания суффикса для адаптера React Router и ссылки на тип ParserBuilder<T>.
Перед внесением правок формируется сводная таблица изменений, требующая подтверждения пользователя. Трансформации выполняются через jscodeshift скриптом scripts/apply.sh. После этого scripts/verify.sh запускает проверку через tsc --noEmit и настроенный линтер. Если компилятор или линтер выдают ошибку, изменения мгновенно откатываются через git restore.
Скрипт прерывает работу на грязном дереве Git, поэтому незакоммиченные файлы придётся спрятать в git stash до запуска модификации.
Какие задачи решает
- Перевести устаревшие вызовы
throttleMsна методlimitUrlUpdates: throttle(N)с добавлением нужных импортов - Заменить громоздкие самодельные связки
useState,useEffectиsetTimeoutна встроенный дебаунс библиотеки nuqs - Найти небезопасные приведения
parseAsJson<T>()и подставить проверку через валидатор Zod или заглушку тайпгарда - Уточнить пути импорта адаптера
nuqs/adapters/react-routerна актуальный путь/v6 - Обновить устаревшие тайпинги
ParserBuilder<T>наSingleParserBuilder<T>по всей кодовой базе
Примеры запросов агенту
- Обнови вызовы nuqs в проекте до версии 2.5 и покажи предварительный отчёт с изменениями
- Просканируй репозиторий на устаревшие паттерны nuqs и примени трансформации jscodeshift
- Найди ручной debounce вокруг useQueryState и перепиши его на limitUrlUpdates из nuqs
Как установить nuqs-codemod-runner
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code2Вручную: положить файлы
~/.claude/skills/nuqs-codemod-runner/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/nuqs-codemod-runner/
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a codex2Вручную: положить файлы
.agents/skills/nuqs-codemod-runner/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a cursor2Вручную: положить файлы
.cursor/skills/nuqs-codemod-runner/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install pproenca/dot-skills skills/.curated/nuqs-codemod-runner2Вручную: положить файлы
.github/skills/nuqs-codemod-runner/SKILL.md1Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a gemini-cli2Командой платформы
gemini skills install https://github.com/pproenca/dot-skills --path skills/.curated/nuqs-codemod-runnerВручную: положить файлы
.devin/skills/nuqs-codemod-runner/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о nuqs-codemod-runner
Как установить nuqs-codemod-runner в Claude Code?
Выполните команду npx skills add pproenca/dot-skills --skill nuqs-codemod-runner -a claude-code. Файл манифеста будет добавлен в путь ~/.claude/skills/nuqs-codemod-runner/SKILL.md.
Что делает скилл nuqs-codemod-runner?
Он запускает аудит TypeScript и JavaScript файлов, находит устаревшие конструкции nuqs версий младше 2.5, выводит таблицу до и после, а затем выполняет AST-трансформации с последующей проверкой типов.
Что произойдёт, если сборка TypeScript сломается после обновления?
Встроенный скрипт верификации verify.sh отслеживает статус tsc --noEmit и команды линтера. При обнаружении любой ошибки процесс выполняет команду git restore для всех затронутых файлов, возвращая код к исходному состоянию.
Исходный текст
SKILL.md · MIT
---
name: nuqs-codemod-runner
description: Migrates a nuqs codebase off pre-v2.5 patterns — deprecated `throttleMs`, hand-rolled setTimeout/useState debounce around `useQueryState`, unchecked `parseAsJson` casts, unversioned `nuqs/adapters/react-router` imports, or `ParserBuilder<T>` type references. Scans the repo, produces a dry-run report, asks for confirmation, applies AST codemods, then runs `tsc --noEmit` + the user's lint as a gate. Trigger even if the user only mentions "upgrade nuqs" or "migrate to nuqs v2.5+" without naming the specific patterns — they almost always exist in pre-v2.5 codebases.
---
# 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](../nuqs/SKILL.md) 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`](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`](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`](../nuqs/) — Best-practice reference for nuqs v2.5+. This skill rewrites legacy code; that skill defines the target.
## Gotchas
See [`gotchas.md`](gotchas.md) for failure modes discovered during use.
© pproenca · MIT · pproenca/dot-skills