Guide · Open source

How to use jscodeshift: write and run codemods

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

jscodeshift is a free, MIT-licensed toolkit for running codemods, which are scripts that automatically rewrite source code, over many JavaScript or TypeScript files at once. It is aimed at large codebases where the same change has to be made in many places. After this guide you will know how to install it, write a small transform module, and run it with a dry run first so you can see how many files would change.

jscodeshiftmeta/jscodeshift · ★ 10k · MIT Install options & downloads

Quick start

1Install the runner. Install jscodeshift globally with npm, which needs Node.js and npm already on your machine.
2Write a transform. Create a transform.js file that exports a function taking fileInfo, api and options, and returns the changed source.
3Test with a dry run. Run jscodeshift with -t and --dry so no files are changed, and review the summary.
4Inspect output. Add --print to see the transformed files on stdout before you commit to the change.
5Run on the codebase. Remove --dry and point jscodeshift at your source directory to apply the transform.
6Check the summary. Read the counts of ok, unmodified, skipped and error results to confirm the change applied where expected.

What jscodeshift includes

The README describes two main parts. The first is a runner, which executes your transform for each file you pass to it and outputs a summary of how many files were or were not transformed. The second is a wrapper around recast, a tool that transforms code syntax trees and tries to preserve the original style of the code as much as possible. The wrapper offers a different, jQuery-like API for navigating and editing the syntax tree.

Install jscodeshift with npm

You need Node.js and npm. Install jscodeshift globally from npm with the command below. The README says this installs the runner as the command jscodeshift.

$ npm install -g jscodeshift

Write a transform module

A transform is a module that exports a function. The function receives fileInfo (with path and source), api (with the jscodeshift library, a stats function and a report function) and options. It returns the changed source. If it returns a string that differs from the input, the file counts as transformed. If it returns the same string, the transform is unsuccessful. If it returns nothing, the file is not supposed to be transformed, which the README describes as ok.

The README gives this example, which renames every variable declarator named foo to bar:

Return the changed source to mark a file as transformed.
Return the same source to mark it as unsuccessful.
Return nothing to skip a file.

module.exports = function(fileInfo, api, options) {
  return api.jscodeshift(fileInfo.source)
    .findVariableDeclarators('foo')
    .renameTo('bar')
    .toSource();
}

Run a dry run before changing files

Use the --dry flag to see what would happen without writing changes. The README notes that the summary reports how many files were ok, unmodified, skipped or had errors. Adding --print outputs transformed files to stdout, which the README says is useful for development. The -t option points to your transform file; it defaults to transform.js in the current directory.

-t, --transform=FILE sets the transform path, which can be a local path or a URL.
-d, --dry performs a dry run with no file changes.
-p, --print prints transformed files to stdout.
--extensions=EXT limits files by extension; the default is js.
--parser=babel|babylon|flow|ts|tsx selects the parser.

$ jscodeshift -t myTransform.js src

Choose a parser for TypeScript or Flow

The CLI accepts a --parser option with the values babel, babylon, flow, ts or tsx, and its default is babel. A transform module can also export a parser value, either one of those strings or a parser object compatible with recast and the estree spec. The README's example sets module.exports.parser to 'flow' for a Flow transform.

module.exports.parser = 'flow';

Learn the basics of the recast-based API

The jscodeshift wrapper works on the abstract syntax tree (AST), so you need a basic understanding of recast and ASTs to use it well. The README says this understanding is needed for the API. Each AST node is a plain JavaScript object with a specific set of fields. Start with small, simple transforms and check the output with --dry and --print before you run anything across a whole project.

What people use it for

Renaming a variable or function consistently across many files in a large JavaScript codebase.
Migrating code from one API or syntax to a new one across a TypeScript project.
Counting how often a construct appears in source files using the stats function during a dry run.
Writing a reusable codemod that a maintainer shares with other projects.

Frequently asked questions

Is jscodeshift free to use?

Yes. The project is licensed under MIT, which is stated in the project details. You can use it, including in commercial work, under that licence's terms.

What do I need to install jscodeshift?

The README lists Node.js and npm as prerequisites. Install it from npm with npm install -g jscodeshift, which installs a command named jscodeshift.

Does jscodeshift work with TypeScript?

Yes. The README says jscodeshift runs codemods over multiple JavaScript or TypeScript files, and the CLI accepts --parser values ts and tsx. The README also says transform modules can be written in TypeScript as of v0.6.1.

How do I test a jscodeshift transform without changing files?

Use the --dry flag, which the README describes as a dry run with no changes made to files. Add --print to see transformed output. The summary shows how many files would be changed.

What is the difference between jscodeshift and recast?

Recast is an AST-to-AST transform tool that tries to preserve original code style. jscodeshift includes a wrapper around recast with a jQuery-like API and adds a runner that applies a transform across many files. The README says you need to understand recast and ASTs to use the jscodeshift API well.

What are alternatives to jscodeshift?

Projects listed as comparable are recast, ts-morph, codemod (Facebook's Codemod tool) and comby. Recast is the library jscodeshift wraps, so it is useful if you want lower-level control.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

jscodeshift suits engineers who need the same mechanical refactor applied across many JavaScript or TypeScript files, and who are comfortable learning basic AST concepts. If you only need to edit a few files by hand, or you want a ready-made app with a graphical interface, the effort of writing a transform is not worth it, so pick a simpler editor or a different tool.

Install options & downloads