A codemod is a script that rewrites source code automatically, usually by editing the syntax tree instead of searching text. Use one when a major upgrade needs the same mechanical change in many files, such as a renamed function or moved import. Review the result like any other pull request.
What a codemod actually does
A text search and replace sees characters. A codemod sees structure. The jscodeshift project describes itself as a toolkit for running codemods over multiple JavaScript or TypeScript files, with a runner that applies a transform to each file and reports how many files changed. It wraps recast, which tries to preserve the style of the original code as much as possible.
OpenRewrite takes the same idea to Java and other languages. Its documentation describes an engine that runs prepackaged recipes for common framework migrations, security fixes and style consistency. Angular ships its own version: ng update runs code transformations that the Angular team says they test across a very large number of projects at Google.
So there are three flavors worth knowing: a generic toolkit you write transforms for, a recipe catalog someone else maintains, and a transform the framework authors ship with the upgrade.
Where codemods help and where they stop
| Change type | Codemod fit |
|---|---|
| Renamed API with identical behavior | Strong |
| Moved or renamed import path | Strong |
| Changed argument order or shape | Good, if the pattern is consistent |
| Behavior change under the same name | Weak, needs a human and a test |
| Deprecated API with no direct replacement | Not suitable |
| Configuration and build file changes | Depends on the tool |
The pattern is simple. If the old and new code are equivalent, a script can do it. If the new code means something different, the script can only move the problem somewhere harder to see.
A safe way to run one
- Start from a green build on the version you are already on. A failing baseline makes every later failure ambiguous.
- Run the codemod on a clean branch, with no other edits in the same commit.
- Read the diff. Sample files from each area of the code, not only the first page.
- Run the full test suite and any type checks.
- Fix leftovers by hand in separate commits, so reviewers can see which changes were mechanical and which were judgment calls.
- Run the codemod again. A good transform is idempotent, so a second run should change nothing.
Keeping the mechanical commit separate is the habit that pays off most. A reviewer can skim a thousand identical renames in minutes, but not if they are mixed with a hundred hand edits.
Security angle
Codemods are written by people, and a transform can be wrong. Treat third party codemods like any dependency: pin the version, read what it does on a sample, and run it in a branch rather than in a shared checkout. A codemod that touches authentication, input handling or crypto calls deserves a closer read than one that renames a hook.
Also remember that a codemod moves you to the new API. It does not tell you whether a vulnerable version is reachable in your code. That is a separate question, and it decides how urgent the upgrade is.
Try it yourself
Click through it at your own pace, or open it full screen. Look for how a fix is presented as a reviewable change rather than a silent edit.
Quick check
Is a codemod the same as find and replace?
No. A codemod works on the structure of the code, so it can tell a function call from a string that happens to contain the same text.
Do I still need tests if a codemod ran cleanly?
Yes. A clean run means the script finished, not that behavior is unchanged.
Safeguard can open fix pull requests for dependency upgrades with every category set to Manual by default, so a person reviews each change. You can run a free scan at gold.safeguard.sh/scan to see which upgrades matter first.
Sources
Last reviewed: 19 October 2026.
