What is a codemod

Learn what a codemod is, how jscodeshift codemods work, when to use them, and see practical codemod examples for large-scale refactors.

A codemod is a script that reads source code, understands its structure, and rewrites it automatically. Instead of updating files by hand, you define a repeatable transformation once and run it across a codebase. If you are completely new to the underlying data model, start with Understanding ASTs.

Codemods are especially useful when a change is:

  • Repetitive across many files
  • Easy to describe as a rule
  • Tedious or risky to do manually
  • Part of a migration, upgrade, or API change

Why codemods exist

At small scale, a refactor might only touch a few files. At larger scale, the same change can affect hundreds or thousands of call sites, imports, props, or patterns.

That is where codemods help:

  • They make large changes consistent
  • They reduce manual mistakes
  • They speed up framework and library migrations
  • They give teams a repeatable way to roll out breaking changes

For example, a codemod can:

  • Rename an imported symbol
  • Replace deprecated props
  • Move imports to a new package
  • Convert one API shape into another
  • Add or remove wrapper components

These patterns show up repeatedly in guides like Import manipulation, React & JSX, and Typescript.

How a codemod works

Most codemods do the same basic thing:

  1. Parse a file into an AST
  2. Find the code pattern you care about
  3. Modify, insert, or remove nodes
  4. Print the updated source code back to disk

Because codemods operate on syntax trees rather than raw text, they are far more reliable than find-and-replace for structural changes.

In the JavaScript ecosystem, one of the most common tools for writing codemods is jscodeshift. jscodeshift lets you parse files into ASTs, query for node types, and print the updated code after your transform runs. If you want to move from the concept to a working transform, continue to Your first codemod.

JSCodeshift codemod example

Here is a minimal jscodeshift codemod that renames imports from old-package to new-package:

export default function transform(file, { jscodeshift: j }, options) {
  const source = j(file.source);

  source
    .find(j.ImportDeclaration, {
      source: { value: 'old-package' }
    })
    .forEach((path) => {
      path.node.source = j.stringLiteral('new-package');
    });

  return source.toSource(options.printOptions);
}

Given this input:

import { Button } from 'old-package';
import { Card } from 'other-package';

The codemod outputs:

import { Button } from 'new-package';
import { Card } from 'other-package';

This is a good example of what codemods do best: small, mechanical changes applied consistently everywhere.

JSCodeshift JSX example

Codemods are also useful for React migrations. For example, if a component prop changes from isDisabled to disabled, a jscodeshift transform can update JSX automatically:

export default function transform(file, { jscodeshift: j }, options) {
  const source = j(file.source);

  source
    .find(j.JSXAttribute, {
      name: { type: 'JSXIdentifier', name: 'isDisabled' }
    })
    .forEach((path) => {
      path.node.name = j.jsxIdentifier('disabled');
    });

  return source.toSource(options.printOptions);
}

Input:

<Button isDisabled>Save</Button>

Output:

<Button disabled>Save</Button>

Codemods vs search and replace

Text replacement only sees characters. A codemod sees code structure.

That difference matters when you need to distinguish between things like:

  • A real import and a similar-looking string
  • A JSX prop and a variable with the same name
  • A specific function call shape and unrelated code nearby

If the change depends on syntax, scope, imports, or AST node types, a codemod is usually the right tool.

When to use a codemod

Use a codemod when you need to automate mechanical code changes such as:

  • Library upgrades
  • Design system migrations
  • Renaming APIs
  • Standardizing patterns across a repo
  • Cleaning up deprecated usage before removal

If the transformation needs runtime parameters, user input, or version-aware behavior, see Parameterized Codemods.

Avoid codemods when the change is mostly subjective or requires deep product-level decisions in every file. Codemods are best at deterministic transformations.

What codemods are not good at

Codemods are powerful, but they are not magic. They can struggle when:

  • The target pattern is highly ambiguous
  • The correct output depends on runtime behavior
  • The codebase uses many inconsistent patterns
  • A migration needs product context that is not visible in the source

In practice, the best migrations often combine codemods with manual review, tests, and linting. It is also worth reading Best practices and Codemodding Gotchas before running a transform broadly.

A simple example

Imagine a component API changes from isDisabled to disabled. A codemod can find every matching JSX attribute and rewrite it automatically.

-<Button isDisabled>Save</Button>
+<Button disabled>Save</Button>

That same rule can then be applied across an entire repository in seconds.

If you want to build transformations like this yourself, the most common workflow is:

  1. Parse the file with jscodeshift
  2. Find the matching AST nodes
  3. Rewrite the nodes you care about
  4. Return the transformed source

Where to go next

If you are new to codemods, the next two steps are:

  1. Learn how code is represented as an AST in Understanding ASTs
  2. Build a real transform in Your first codemod

After that, use these guides based on the kind of codemod you are writing:

DeploymentsYour first codemod