jscodeshift Documentation

Technical Documentation: facebook/jscodeshift

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

[jscodeshift](https://jscodeshift.com/) [](https://opensource.fb.com/support-ukraine) [](https://github.com/facebook/jscodeshift/actions/workflows/test.yml?query=branch%3Amain)

jscodeshift is a toolkit for running codemods over multiple JavaScript or
TypeScript files.
It provides:

• A runner, which executes the provided transform for each file passed to it.
  It also outputs a summary of how many files have (not) been transformed.
• A wrapper around recast, providing a different API. Recast is an
  AST-to-AST transform tool and also tries to preserve the style of original code
  as much as possible.

Install Copy Chapter

Get jscodeshift from npm:

$ npm install jscodeshift

This will install the runner as jscodeshift.

VSCode Debugger Copy Chapter

Configure VSCode to debug codemods

Usage (CLI) Copy Chapter

See the website for full documentation.

The CLI provides the following options:

/* Detailed source-code truncated for AI context efficiency. */

This passes the source of all passed through the transform module specified
with -t or --transform (defaults to transform.js in the current
directory). The next section explains the structure of the transform module.

Usage (JS) Copy Chapter

const {run: jscodeshift} = require('jscodeshift/src/Runner')
const path = require('node:path');

const transformPath = path.resolve('transform.js')
const paths = ['foo.js', 'bar']
const options = {
  dry: true,
  print: true,
  verbose: 1,
  // ...
}

const res = await jscodeshift(transformPath, paths, options)
console.log(res)
/*
{
  stats: {},
  timeElapsed: '0.001',
  error: 0,
  ok: 0,
  nochange: 0,
  skip: 0
}
*/

Transform module Copy Chapter

The transform is simply a module that exports a function of the form:

module.exports = function(fileInfo, api, options) {
  // transform `fileInfo.source` here
  // ...
  // return changed source
  return source;
};

As of v0.6.1, this module can also be written in TypeScript.

Arguments Copy Section

`fileInfo`

Holds information about the currently processed file.

`api`

This object exposes the jscodeshift library and helper functions from the
runner.

jscodeshift is a reference to the wrapper around recast and provides a
jQuery-like API to navigate and transform the AST. Here is a quick example,
a more detailed description can be found below.

/**
 * This replaces every occurrence of variable "foo".
 */
module.exports = function(fileInfo, api, options) {
  return api.jscodeshift(fileInfo.source)
    .findVariableDeclarators('foo')
    .renameTo('bar')
    .toSource();
}

Note: This API is exposed for convenience, but you don't have to use it.
You can use any tool to modify the source.

stats is a function that only works when the --dry options is set. It accepts
a string, and will simply count how often it was called with that value.

At the end, the CLI will report those values. This can be useful while
developing the transform, e.g. to find out how often a certain construct
appears in the source(s).

report allows you to print arbitrary strings to stdout. This can be
useful when other tools consume the output of jscodeshift. The reason to not
directly use process.stdout in transform code is to avoid mangled output when
many files are processed.

`options`

Contains all options that have been passed to runner. This allows you to pass
additional options to the transform. For example, if the CLI is called with

$ jscodeshift -t myTransforms fileA fileB --foo=bar

options would contain {foo: 'bar'}.

Return value Copy Section

The return value of the function determines the status of the transformation:

• If a string is returned and it is different from passed source, the
  transform is considered to be successful.
• If a string is returned but it's the same as the source, the transform
  is considered to be unsuccessful.
• If nothing is returned, the file is not supposed to be transformed (which is
  ok).

The CLI provides a summary of the transformation at the end. You can get more
detailed information by setting the -v option to 1 or 2.

You can collect even more stats via the stats function as explained above.

Parser Copy Section

The transform file can let jscodeshift know with which parser to parse the source files (and features like templates).

To do that, the transform module can export parser, which can either be one
of the strings "babel", "babylon", "flow", "ts", or "tsx",
or it can be a parser object that is compatible with recast and follows the estree spec.

Example: specifying parser type string in the transform file

module.exports = function transformer(file, api, options) {
  const j = api.jscodeshift;
  const rootSource = j(file.source);

  // whatever other code...

  return rootSource.toSource();
}

// use the flow parser
module.exports.parser = 'flow';

Example: specifying a custom parser object in the transform file

module.exports = function transformer(file, api, options) {
  const j = api.jscodeshift;
  const rootSource = j(file.source);

  // whatever other code...

  return rootSource.toSource();
}

module.exports.parser = {
  parse: function(source) {
    // return estree compatible AST
  },
};

Example output Copy Section

$ jscodeshift -t myTransform.js src
Processing 10 files...
Spawning 2 workers with 5 files each...
All workers done.
Results: 0 errors 2 unmodified 3 skipped 5 ok

The jscodeshift API Copy Chapter

As already mentioned, jscodeshift also provides a wrapper around recast.
In order to properly use the jscodeshift API, one has to understand the basic
building blocks of recast (and ASTs) as well.

Core Concepts Copy Section

AST nodes

An AST node is a plain JavaScript object with a specific set of fields, in
accordance with the Mozilla Parser API. The primary way to identify nodes
is via their type.

For example, string literals are represented via Literal nodes, which
have the structure

// "foo"
{
  type: 'Literal',
  value: 'foo',
  raw: '"foo"'
}

It's OK to not know the structure of every AST node type.
The (esprima) AST explorer is an online tool to inspect the AST
for a given piece of JS code.

Path objects

Recast itself relies heavily on ast-types which defines methods to traverse
the AST, access node fields and build new nodes. ast-types wraps every AST node
into a path object. Paths contain meta-information and helper methods to
process AST nodes.

For example, the child-parent relationship between two nodes is not explicitly
defined. Given a plain AST node, it is not possible to traverse the tree up.
Given a path object however, the parent can be traversed to via path.parent.

For more information about the path object API, please have a look at
ast-types.

Builders

To make creating AST nodes a bit simpler and "safer", ast-types defines a couple
of builder methods, which are also exposed on jscodeshift.

For example, the following creates an AST equivalent to foo(bar):

// inside a module transform
var j = jscodeshift;
// foo(bar);
var ast = j.callExpression(
  j.identifier('foo'),
  [j.identifier('bar')]
);

The signature of each builder function is best learned by having a look at the
definition files
or in the babel/types docs.

Collections and Traversal Copy Section

In order to transform the AST, you have to traverse it and find the nodes that
need to be changed. jscodeshift is built around the idea of collections of
paths and thus provides a different way of processing an AST than recast or
ast-types.

A collection has methods to process the nodes inside a collection, often
resulting in a new collection. This results in a fluent interface, which can
make the transform more readable.

Collections are "typed" which means that the type of a collection is the
"lowest" type all AST nodes in the collection have in common. That means you
cannot call a method for a FunctionExpression collection on an Identifier
collection.

Here is an example of how one would find/traverse all Identifier nodes with
jscodeshift and with recast:

// recast
var ast = recast.parse(src);
recast.visit(ast, {
  visitIdentifier: function(path) {
    // do something with path
    return false;
  }
});

// jscodeshift
jscodeshift(src)
  .find(jscodeshift.Identifier)
  .forEach(function(path) {
    // do something with path
  });

To learn about the provided methods, have a look at the
Collection.js and its extensions.

Extensibility Copy Section

jscodeshift provides an API to extend collections. By moving common operators
into helper functions (which can be stored separately in other modules), a
transform can be made more readable.

There are two types of extensions: generic extensions and type-specific
extensions. Generic extensions are applicable to all collections. As such,
they typically don't access specific node data, but rather traverse the AST from
the nodes in the collection. Type-specific extensions work only on specific
node types and are not callable on differently typed collections.

Examples

// Adding a method to all Identifiers
jscodeshift.registerMethods({
  logNames: function() {
    return this.forEach(function(path) {
      console.log(path.node.name);
    });
  }
}, jscodeshift.Identifier);

// Adding a method to all collections
jscodeshift.registerMethods({
  findIdentifiers: function() {
    return this.find(jscodeshift.Identifier);
  }
});

jscodeshift(ast).findIdentifiers().logNames();
jscodeshift(ast).logNames(); // error, unless `ast` only consists of Identifier nodes

Ignoring files and directories Copy Section

Sometimes there are files and directories that you want to avoid running transforms on. For example, the node_modules/ directory, where the project's installed local npm packages reside, can introduce bugs if any files in it are accidentally transformed by jscodeshift.

The simplest way to avoid many of these unwanted transforms is to pass jscodeshift the --gitignore flag, which uses the glob patterns specified in your project’s .gitignore file to avoid transforming anything in directories such as node_modules/, dist/, etc. In most cases anything you want git to ignore you proabably are also going to want jscodeshift to ignore as well. Please note that the .gitignore file use will be taken from the current working directory from which jscodeshift is being run.

jscodeshift --gitignore mytransform.js

For more custom ignore functionality, the --ignore-pattern and the --ignore-config arguments can be used.

--ignore-pattern takes a .gitignore format glob pattern that specifies file and directory patterns to ignore

jscodeshift --ignore-pattern="js_configuration_files/**/*” mytransform.js

// More than one ignore
jscodeshift --ignore-pattern="first_ignored_dir/**/*” -—ignore-pattern="second_ignored_dir/**/*” mytransform.js

--ignore-config takes one or more paths to files containing lines with .gitignore format glob patterns.

// note: .gitignore is a random made-up filename extension for this example

jscodeshift --ignore-config="MyIgnoreFile.gitignore" mytransform.js

// More than one ignore file
jscodeshift --ignore-pattern="first_ignore_file.gitignore” --ignore-pattern="second_ignore_file.gitignore” mytransform.js

Passing options to [recast] Copy Section

You may want to change some of the output settings (like setting ' instead of " or
changing the end-of-line terminator to \r\n for Windows files).
This can be done by passing config options to recast.

.toSource({quote: 'single'}); // sets strings to use single quotes in transformed code.
// or
.toSource({lineTerminator: '\r\n'}); // sets EOL to use CRLF.

You can also pass options to recast's parse method by passing an object to
jscodeshift as second argument:

jscodeshift(source, {...})

For more details on recast config options, see here.

Unit Testing Copy Section

jscodeshift comes with a simple utility to allow easy unit testing with Jest, without having to write a lot of boilerplate code. This utility makes some assumptions in order to reduce the amount of configuration required:

• The test is located in a subdirectory under the directory the transform itself is located in (eg. __tests__)
• Test fixtures are located in a __testfixtures__ directory

This results in a directory structure like this:

/MyTransform.js
/__tests__/MyTransform-test.js
/__testfixtures__/MyTransform.input.js
/__testfixtures__/MyTransform.output.js

A simple example of unit tests is bundled in the sample directory.

The testUtils module exposes a number of useful helpers for unit testing.

`defineTest`

Defines a Jest/Jasmine test for a jscodeshift transform which depends on fixtures

jest.autoMockOff();
const defineTest = require('jscodeshift/dist/testUtils').defineTest;
defineTest(__dirname, 'MyTransform');

An alternate fixture filename can be provided as the fourth argument to defineTest.
This also means that multiple test fixtures can be provided:

defineTest(__dirname, 'MyTransform', null, 'FirstFixture');
defineTest(__dirname, 'MyTransform', null, 'SecondFixture');

This will run two tests:

• __testfixtures__/FirstFixture.input.js
• __testfixtures__/SecondFixture.input.js

`defineInlineTest`

Defines a Jest/Jasmine test suite for a jscodeshift transform which accepts inline values

This is a more flexible alternative to defineTest, as this allows to also provide options to your transform

const defineInlineTest = require('jscodeshift/dist/testUtils').defineInlineTest;
const transform = require('../myTransform');
const transformOptions = {};
defineInlineTest(transform, transformOptions, 'input', 'expected output', 'test name (optional)');

An optional testOptions object can be passed as the last argument to select the
parser used to run the transform, e.g. defineInlineTest(transform, transformOptions, 'input', 'expected output', 'test name', { parser: 'tsx' }).

`defineSnapshotTest`

Similar to defineInlineTest but instead of requiring an output value, it uses Jest's toMatchSnapshot()

const defineSnapshotTest = require('jscodeshift/dist/testUtils').defineSnapshotTest;
const transform = require('../myTransform');
const transformOptions = {};
defineSnapshotTest(transform, transformOptions, 'input', 'test name (optional)');

Like defineInlineTest, an optional testOptions object (e.g. { parser: 'tsx' }) can be passed as the last argument to select the parser.

For more information on snapshots, check out Jest's docs

`defineSnapshotTestFromFixture`

Similar to defineSnapshotTest but will load the file using same file-directory defaults as defineTest

const defineSnapshotTestDefault = require('jscodeshift/dist/testUtils').defineSnapshotTestDefault;
const transform = require('../myTransform');
const transformOptions = {};
defineSnapshotTestFromFixture(__dirname, transform, transformOptions, 'FirstFixture', 'test name (optional)');

An optional testOptions object (e.g. { parser: 'tsx' }) can be passed as the last argument. Its parser is used both to resolve the fixture's file extension (.input.tsx) and to run the transform.

`applyTransform`

Executes your transform using the options and the input given and returns the result.
This function is used internally by the other helpers, but it can prove useful in other cases.
(bear in mind the transform module can be asynchronous. In that case, applyTransform will return a Promise with the transformed code. Otherwise, it will directly return the transformed code as a string).

const applyTransform = require('jscodeshift/dist/testUtils').applyTransform;
const transform = require('../myTransform');
const transformOptions = {};
const output = applyTransform(transform, transformOptions, 'input');

ES modules

If you're authoring your transforms and tests using ES modules, make sure to import the transform's parser (if specified) in your tests:

// MyTransform.js
export const parser = 'flow'
export default function MyTransform(fileInfo, api, options) {
  // ...
}

// __tests__/MyTransform-test.js
import { defineInlineTest } from 'jscodeshift/dist/testUtils
import * as transform from '../MyTransform

console.log(transform.parser) // 'flow'

defineInlineTest(transform, /* ... */)

Example Codemods Copy Section

• react-codemod - React codemod scripts to update React APIs.
• js-codemod - Codemod scripts to transform code to next generation JS.
• js-transforms - Some documented codemod experiments to help you learn.
• fix-js - Codemods to fix some ESLint issues

Local Documentation Server Copy Section

To update docs in /docs, use npm run docs.

To view these docs locally, use npx http-server ./docs

VSCode Debugging Copy Chapter

It's recommended that you set up your codemod project to all debugging via the VSCode IDE. When you open your project in VSCode, add the following configuration to your launch.json debugging configuration.

/* Detailed source-code truncated for AI context efficiency. */

Once this has been added to the configuration

1. Install jscodeshift as a package if you haven't done so already by running the command npm install --save jscodeshift. The debug configuration will not work otherwise.
2. Once the jscodeshift local package has been installed, go to the VSCode file tree and select the file on which you want to run the transform. For example, if you wanted to run codemod transforms of foo.js file, you would click on the entry for foo.js file in your project tree.
3. Select "Debug Transform" from the debugging menu's options menu.
4. Click the "Start Debugging" button on the VSCode debugger.
5. You will be then prompted for the name of jscodeshift transform file. Enter in the name of the transform file to use. If no name is given it will default to transform.js
6. Select the parser to use from the presented selection list of parsers. The transform will otherwise default to using the babel parser.
7. The transform will then be run, stopping at any breakpoints that have been set.
8. If there are no errors and the transform is complete, then the results of the transform will be printed in the VSCode debugging console. The file with the contents that have been transformed will not be changed, as the debug configuration makes use the jscodeshift --dry option.

Recipes Copy Section

• Retain leading comment(s) in file when replacing/removing first statement

Overview (`.changeset/README.md`) Copy Section

Changesets

Hello and welcome! This folder has been automatically generated by @changesets/cli, a build tool that works
with multi-package repos, or single-package repos to help you version and publish your code. You can
find the full documentation for it in our repository

We have a quick list of common questions to get you started engaging with this project in
our documentation

Overview (`website/README.md`) Copy Section

jscodeshift docs

🚀 Project Structure Copy Chapter

.
├── public/
├── src/
│   ├── assets/
│   ├── content/
│   │   ├── docs/
│   │   └── config.ts
│   └── env.d.ts
├── astro.config.mjs
├── package.json
└── tsconfig.json

Starlight looks for .md or .mdx files in the src/content/docs/ directory. Each file is exposed as a route based on
its file name.

Images can be added to src/assets/ and embedded in Markdown with a relative link.

Static assets, like favicons, can be placed in the public/ directory.

🧞 Commands Copy Chapter

All commands are run from the root of the project, from a terminal:

👀 Want to learn more? Copy Chapter

Check out Starlight’s docs, read the Astro documentation,
or jump into the Astro Discord server.

Website Src Content Docs Index (`website/src/content/docs/index.mdx`) Copy Section

title: Docs
template: doc
hero:
tagline: Get started with building and running jscodeshift codemods.
actions:
- text: Get started
link: /overview/introduction/
icon: right-arrow
variant: primary
- text: GitHub
link: https://github.com/facebook/jscodeshift
icon: external

Website Src Content Docs Overview Introduction (`website/src/content/docs/overview/introduction.mdx`) Copy Section

title: Introduction Copy Chapter

import { Steps, LinkCard, Card, CardGrid } from '@astrojs/starlight/components';

jscodeshift is a toolkit for building and running codemods over multiple JavaScript or TypeScript files. It provides:

• A runner, which executes the provided transform for each file passed to it. It also outputs a summary of how many files have not been transformed.
• A wrapper around recast, providing a different API. Recast is an AST-to-AST transform tool and also tries to preserve the style of original code
  as much as possible.

How does jscodeshift work? Copy Chapter

First, jscodeshift takes your JavaScript code and converts it into an Abstract Syntax Tree (AST). An AST is a tree representation of your code where each node represents a different part of the code, like variables, functions, and expressions.

$ npm install jscodeshift

jscodeshift [OPTION]... PATH...

jscodeshift [OPTION]... -t TRANSFORM_PATH PATH...

jscodeshift [OPTION]... -t URL PATH...

jscodeshift [OPTION]... --stdin < file_list.txt