API Reference

jscodeshift has around 25 APIs to help developers easily detect and transform any JS/TS code.

Generally, creating a codemod involves two main tasks: detection and transformation.

1. Detection

   Detecting a specific pattern in a large codebase can be expensive, so this task is often divided into two passes.

   1. First pass

      In the first pass, we perform an initial scope reduction of the AST nodes to significantly reduce the search space and produce a collection of AST nodes to process.

   2. Second pass

      In the second pass, we process and filter the nodes collection to pinpoint the specific AST nodes that need transformation.

2. Transformation

   Once we detect the desired nodes, we transform the AST and produce the modified code.

For jscodeshift, we have a set of APIs for each part of the codemod process (initial traversal, filtering, transformation), as detailed below. jscodeshift accepts —parser as argument. We can select from the list of parser that are currently supported, all those parsers should be compatible with estree spec and have same AST grammar. It’s important to know the AST grammar for describing the nodes in the codemod.

Refer to the jscodeshift node types.

Building jscodeshift codemods

Core API

Node Traversal APIs

Node Transformation APIs

Core API

jscodeshift

The main function that returns the jscodeshift instance.

Parameters: source (String): The source code to be transformed.

Example:

const jscodeshift = require('jscodeshift');
const sourceCode = `const a = 1;`;
const j = jscodeshift(sourceCode);

Node Traversal APIs

Below are APIs that often used in the initial scope reduction phase (source). The input is usually the whole file, and the output is a collection of nodes.

find

Finds nodes that match the provided type.

Parameters: type (String or Function): The type of nodes to find.

Example:

const variableDeclarations = j.find(j.VariableDeclaration);

closestScope

Finds the closest enclosing scope of a node. Useful for determining the scope context of variables and functions.

Example:

const closestScopes = j.find(j.Identifier).closestScope();

closest

Finds the nearest parent node that matches the specified type. The child node must be obtained from a previous function call, such as find.

Parameters:type (String or Function): The type of ancestor to find.

const closestFunction = j.find(j.Identifier).closest(j.FunctionDeclaration);

getVariableDeclarators

Retrieves variable declarators from the current collection. If the callback function returns a falsy value, the element is not included in the result.

Parameters:callback (Function): A function that returns the name of the variable to find.

Example:

const variableDeclarators = j.find(j.Identifier).getVariableDeclarators(path => path.value.name);

findVariableDeclarators (source)

Finds variable declarators by name.

Parameters: name (String): The name of the variable to find.

Example:

const variableDeclarators = j.findVariableDeclarators('a');

Below are the APIs that are often used in the second phase, which is the detailed node filtering (source). The input of this phase is usually a collection of nodes, and the output, is specific nodes to transform.

filter

Filters nodes based on a predicate function.

Parameters: predicate (Function): A function to test each element.

Example:

const constDeclarations = j.find(j.VariableDeclaration)
  .filter(path => path.node.kind === 'const');

forEach

Iterates over each node in the collection.

Parameters: callback (Function): A function to call for each node.

Example:

j.find(j.VariableDeclaration).forEach(path => {
  console.log(path.node);
});

some

some checks if at least one element in the collection passes the test implemented by the provided function.

Parameters: callback: A function that tests each element. The callback function takes three arguments:

• path: The current element being processed.
• index: The index of the current element.
• array: The array some was called upon.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1; const b = 2; const c = 3;`);

const hasVariableA = root.find(j.VariableDeclarator).some(path => path.node.id.name === 'a');
console.log(hasVariableA); // true

every

every checks if all elements in the collection pass the test implemented by the provided function.

Parameters: callback: A function that tests each element. The callback function takes three arguments:

• path: The current element being processed.
• index: The index of the current element.
• array: The array every was called upon.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1; const b = 2; const c = 3;`);

const allAreConst = root.find(j.VariableDeclaration).every(path => path.node.kind === 'const');
console.log(allAreConst); // true

map

Maps each node in the collection to a new value.

Parameters:callback (Function): A function to call for each node.

Example:

const variableNames = j.find(j.VariableDeclaration)
  .map(path => path.node.declarations.map(decl => decl.id.name));

size

Returns the number of nodes in the collection.

Example:

const numberOfNodes = j.find(j.VariableDeclaration).size();

length

length returns the number of elements in the collection.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1; const b = 2; const c = 3;`);

const varCount = root.find(j.VariableDeclarator).length;
console.log(varCount); // 3

nodes

Returns the AST nodes in the collection.

Example:

const nodes = j.find(j.VariableDeclaration).nodes();

paths

Returns the paths of the found nodes.

Example:

const paths = j.find(j.VariableDeclaration).paths();

getAST

getAST returns the root AST node of the collection.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1;`);

const ast = root.getAST();
console.log(ast.type); // File

get

Gets the first node in the collection.

Example:

const firstVariableDeclaration = j.find(j.VariableDeclaration).get();

at

Navigates to a specific path in the AST.

Parameters: index (Number): The index of the path to navigate to.

Example:

const secondVariableDeclaration = j.find(j.VariableDeclaration).at(1);

getTypes

getTypes returns the set of node types present in the collection.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1; const b = 2;`);

const types = root.find(j.VariableDeclarator).getTypes();
console.log(types); // Set { 'VariableDeclarator' }

isOfType

isOfType checks if the node in the collection is of a specific type.

Parameters: type: The type to check against.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1;`);

const isVariableDeclarator = root.find(j.VariableDeclarator).at(0).isOfType('VariableDeclarator');
console.log(isVariableDeclarator); // true

Node Transformation APIs

Below are the APIs used in node transformations. (source)

replaceWith

Replaces the current node(s) with a new node.

Parameters: newNode (Node or Function): The new node or a function that returns a new node.

Example:

j.find(j.Identifier)
  .replaceWith(path => j.identifier(path.node.name.toUpperCase()));

insertBefore

Inserts a node before the current node.

Parameters: newNode (Node): The node to insert.

Example:

j.find(j.FunctionDeclaration)
  .insertBefore(j.expressionStatement(j.stringLiteral('Inserted before')));

insertAfter

Inserts a node after the current node.

Parameters: newNode (Node): The node to insert.

Example:

j.find(j.FunctionDeclaration)
  .insertAfter(j.expressionStatement(j.stringLiteral('Inserted after')));

remove

Removes the current node(s).

Example:

j.find(j.VariableDeclaration).remove();

renameTo (source)

renameTo renames the nodes in the collection to a new name.

Parameters: newName: The new name to rename to.

Example:

const j = require('jscodeshift');

const root = j(`const a = 1; const b = 2;`);

root.find(j.Identifier, { name: 'a' }).renameTo('x');

console.log(root.toSource()); // const x = 1; const b = 2;

These descriptions and examples should give you a clear understanding of how to use each of these jscodeshift APIs.

toSource

Converts the transformed AST back to source code.

Parameters: options (Object): Optional formatting options.

Example:

const transformedSource = j.toSource({ quote: 'single' });