Codemods are just ASTs with manners

Why not find-and-replace?

Say a library renames fetchUser(id) to getUser({ id }). A regex can find the text fetchUser(, but it can’t tell a call from a comment, a string, or a local variable that happens to share the name. And it definitely can’t move the argument into an object.

A codemod doesn’t look at text at all. It parses the file into an ASTAST (abstract syntax tree)Your code parsed into a tree of nodes: a function call, its arguments, an identifier. Tools change the tree, not the text.Got it, a tree where every node knows exactly what it is.

The four steps

1. 1. Parse

   Read the source file and turn it into a tree of nodes. jscodeshift uses recast for this, which also remembers the original formatting of every node.

2. 2. Find

   Search the tree for the nodes you care about. Here: every CallExpression whose callee is the identifier fetchUser.

3. 3. Change

   Replace or edit those nodes. Rename the callee to getUser and wrap the first argument in an object: { id }.

4. 4. Print

   Turn the tree back into source. Untouched nodes are printed exactly as they were, so the diff only shows real changes.

The code

Here’s the whole transform with jscodeshiftjscodeshiftA toolkit from Meta for running codemods on JavaScript and TypeScript, built on recast.Got it:

export default function transformer(file, api) {
  const j = api.jscodeshift;

  return j(file.source)
    .find(j.CallExpression, { callee: { name: 'fetchUser' } })
    .forEach((path) => {
      const [id] = path.node.arguments;
      path.node.callee.name = 'getUser';
      path.node.arguments = [j.objectExpression([j.objectProperty(j.identifier('id'), id)])];
    })
    .toSource();
}

deep dive Why the formatting survives

recastrecastA parser and printer that remembers the original formatting, so only the parts you changed get reprinted.Got it keeps a copy of the original source for every node it parses. When you call toSource(), it walks the tree and reuses the original text for any node you didn’t modify. Only modified nodes are pretty-printed from scratch. That’s why a codemod across thousands of files produces a diff a human can actually review.

The trade-off: if you replace a big node (say, a whole function), recast has to reprint all of it, and its formatting may differ from your Prettier config. Run Prettier after the codemod to settle it.

Running it safely

• Write fixtures: an input file and the output you expect, for the common case and the weird ones.
• Run with --dry --print first and read a sample of the output.
• Commit before running, so git diff shows exactly what changed and git checkout . undoes it.