jscodeshift-codemods_skill

Overview

This skill helps you write and debug AST-based codemods using jscodeshift for automated, repeatable code transformations. It focuses on safe, minimal AST edits, test-driven development, and handling edge cases so codemods can run reliably across large codebases. The goal is to preserve formatting and comments while making deterministic changes at scale.

How this skill works

You author transforms that parse source into an AST via api.jscodeshift, locate target nodes with the Collection API, and mutate or replace nodes before returning the modified source. Tests use fixture-based defineTest to drive TDD: create input/output fixtures, verify failing tests, implement the transform, then add edge-case fixtures. Use dry runs, verbose stats, and fail-on-error flags to validate at scale.

When to use it

• Library or API migrations (e.g., router, testing libraries)
• Large-scale refactors like renames or API shape changes
• Enforcing or standardizing patterns across a repo
• Removing deprecated or unsafe APIs systematically
• Avoid for one-off edits, semantic/business-logic changes, or non-deterministic transformations

Best practices

• Always write failing fixture tests first (TDD) and add edge-case fixtures before wide runs
• Make surgical AST edits—mutate nodes instead of rebuilding to preserve comments and formatting
• Scope matches narrowly to avoid over-matching; verify imports/bindings to ensure correct context
• Ensure idempotency: skip or detect already-transformed code and avoid duplicate imports
• Dry-run and review samples before applying; run with --fail-on-error in CI for safety

Example use cases

• Rename a deprecated named import and update all call sites safely across TSX/JSX files
• Change function call argument list into an options object for a public API upgrade
• Replace history.push(...) calls with a new navigate(...) helper while preserving comments
• Add a missing import only when the module is referenced, avoiding duplicate imports
• Standardize a pattern (e.g., transform callback-style to promise-style) across many files