# Codemod React Pipeline > Guided, scripted pipeline for running JSX/TSX/React codemods safely across large legacy codebases. Use when you need to scaffold a codemod, dry-run it, validate its findings, and apply it across many files (50 to 100k+) without breaking the build. Walks the full inner/outer loop with the Codemod CLI (JSSG, ast-grep, workflows). Triggers on large-scale refactor, legacy React migration, codemod a prop/API change, migrate components across the codebase, run a codemod safely, batched/resumable codemod apply, dry-run a codemod. - Skill: `pproenca/codemod-react-pipeline` (Agent Skill, multi-file: 25 files) - Install (CLI): `npx skillmds add pproenca/codemod-react-pipeline` - Raw SKILL.md: https://api.skillmd.com/api/skills/pproenca/codemod-react-pipeline/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: pproenca (https://skillmd.com/u/pproenca) - Updated: 2026-09-09 - Page: https://skillmd.com/skills/pproenca/codemod-react-pipeline --- # Codemod React Pipeline A safe, repeatable workflow for applying **JSX / TSX / React codemods to large legacy codebases** — from a 50-file rename to a 100k-file API migration. It composes the [Codemod CLI](https://docs.codemod.com) (JSSG, ast-grep, workflows) into an inner/outer loop and gates every mass change behind a dry-run plus validation. For the *why* behind each rule it cites, see the sibling [`codemod`](../codemod/) best-practices reference. ## When to Apply Use this skill when: - You're migrating a pattern across a large React/TS codebase (component/prop rename, deprecated API, import swap, hook migration) and a hand-run `codemod jssg run ./t.ts ./src` is too risky. - You need the change to land **incrementally and reviewably** — per-batch commits, resumable on failure, with the build/typecheck/tests green at every checkpoint. - You want to **see and validate the findings** (what would change, and whether it's safe) before touching files at scale. - The transform must be **idempotent** and proven so before mass apply. Don't use it for a one-file edit, or a change better done by hand in a single PR. ## Workflow Overview ``` 00 plan ─▶ 01 scaffold ─▶ 02 inner loop ─▶ 03 dry-run ─▶ 04 validate ─▶ 05 batched apply ─▶ 06 verify goal templates fixture tests preview gates per-batch final + blast (transform/ + 1-file trial + findings (idempotency, apply+verify+commit assertions radius rule/wf/tests) report type/lint/test) (resumable) │ │ └── sentinel ──── required by ──────┘ (on any failure: working tree reverted; fix and re-run — nothing committed yet) ``` | Step | Action | Tool / Script | Risk | |------|--------|---------------|------| | 0 | Capture goal, classify transform, count blast radius | `scripts/00-plan.sh` | read-only | | 1 | Scaffold transform + fixtures + workflow from templates | `scripts/01-scaffold.sh` | write (new files) | | 2 | Fixture tests + single-file trial run (auto-reverted) | `scripts/02-inner-loop.sh` | read-only (reverts) | | 3 | Preview changes; write findings report + dry-run sentinel | `scripts/03-dry-run.sh` | read-only (reverts) | | 4 | Gate: idempotency, typecheck, lint, format, tests | `scripts/04-validate-findings.sh` | read-only (reverts) | | 5 | Apply in resumable batches, verify + commit each | `scripts/05-run-batched.sh` | **destructive** (commits) | | 6 | Final assertions over the whole migration | `scripts/verify.sh` | read-only | A PreToolUse hook (`hooks/hooks.json`) blocks a broad `codemod jssg run` that lacks `--dry-run` when no dry-run sentinel exists — so step 5 (or an ad-hoc apply) cannot skip steps 3–4. ## Requirements - **Codemod CLI** — `npm i -g codemod` (or the scripts fall back to `npx codemod`). Provides `jssg run/test` and `workflow run/validate/resume/status`. - **git** — the pipeline requires a clean tree and makes per-batch checkpoint commits. - **jq** — the scripts read `config.json` with it. - **Your project's gate tooling** — TypeScript, ESLint, Prettier, a test runner (whichever gates you enable in `config.json`). ## Setup Edit `config.json` for the target repo (see each field's `_setup_instructions`): - `src_globs`: the files the codemod may touch (scopes blast radius + gates) - `language`: `tsx` | `jsx` | `typescript` | `javascript` - `typecheck_cmd` / `lint_cmd` / `format_cmd` / `test_cmd`: gate commands (empty disables a gate) - `batch_size`: files per checkpoint in the outer loop - `gates`: per-gate on/off toggles Add your `state_dir` (default `.codemod-pipeline`) to the target repo's `.gitignore`. ## Quick Reference | Script | Purpose | |--------|---------| | `scripts/00-plan.sh "" [name]` | Plan + blast-radius estimate | | `scripts/01-scaffold.sh [--rule]` | Scaffold a JSSG transform (or ast-grep rule) | | `scripts/02-inner-loop.sh [--watch\|--file P\|-u]` | Tight loop: fixture tests / 1-file trial | | `scripts/03-dry-run.sh [--sample N]` | Preview; write findings + sentinel | | `scripts/04-validate-findings.sh ` | Run validation gates | | `scripts/05-run-batched.sh [--batch-size N\|--dry]` | Resumable batched apply + commits | | `scripts/verify.sh ` | Final sign-off assertions | | `scripts/selftest.sh` | Self-test this skill's scripts/assets | ## How to Use 1. From the **target repo root**, run `00-plan.sh ""` and read the generated `plan.md`. 2. `01-scaffold.sh `, then implement `codemods//transform.ts` and its fixtures. 3. Iterate with `02-inner-loop.sh --watch` until fixtures pass; try `--file ` on a real file. 4. `03-dry-run.sh ` and read the findings report; then `04-validate-findings.sh `. 5. Only after gates pass: `05-run-batched.sh ` (resume by re-running it after any fix). 6. `verify.sh ` to confirm the migration is complete and idempotent. See [references/workflow.md](references/workflow.md) for per-step inputs, outputs, failure handling, and rollback; [references/inner-outer-loop.md](references/inner-outer-loop.md) for the mental model; and [references/safety-and-scale.md](references/safety-and-scale.md) for batching and rollback at 100k-file scale. ## Gotchas See [gotchas.md](gotchas.md). The big ones: workflow `commit:` checkpoints are **cloud-only** (the pipeline commits locally instead); always exclude generated/vendored trees; and design for idempotency from the first line. ## Related Skills - [`codemod`](../codemod/) — the best-practices reference (48 rules) this pipeline operationalizes. Steps here cite specific rules (e.g. `test-run-on-subset-first`, `state-use-for-resumability`, `pattern-ensure-idempotency`, `security-minimize-capabilities`).