---
title: API Reference
---
import {Steps, LinkCard, Card, CardGrid} from '@astrojs/starlight/components';
`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](/build/ast-grammar/).
## Building jscodeshift codemods
## Core API
### **`jscodeshift`**
The main function that returns the jscodeshift instance.
**Parameters**: `source` (String): The source code to be transformed.
**Example**:
```jsx
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](https://github.com/facebook/jscodeshift/blob/4851fc8a01036868efb4cf9676f3e97836097376/src/collections/Node.js#L139)). 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**:
```jsx
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**:
```jsx
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.
```jsx
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**:
```jsx
const variableDeclarators = j.find(j.Identifier).getVariableDeclarators(path => path.value.name);
```
### **`findVariableDeclarators` ([source](https://github.com/facebook/jscodeshift/blob/main/src/collections/VariableDeclarator.js))**
Finds variable declarators by name.
**Parameters**: `name` (String): The name of the variable to find.
**Example**:
```jsx
const variableDeclarators = j.findVariableDeclarators('a');
```
Below are the APIs that are often used in the second phase, which is the **detailed node filtering** ([source](https://github.com/facebook/jscodeshift/blob/4851fc8a01036868efb4cf9676f3e97836097376/src/Collection.js)). 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**:
```jsx
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**:
```jsx
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:**
```jsx
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:**
```jsx
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**:
```jsx
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**:
```jsx
const numberOfNodes = j.find(j.VariableDeclaration).size();
```
### `length`
`length` returns the number of elements in the collection.
**Example:**
```jsx
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**:
```jsx
const nodes = j.find(j.VariableDeclaration).nodes();
```
### **`paths`**
Returns the paths of the found nodes.
**Example**:
```jsx
const paths = j.find(j.VariableDeclaration).paths();
```
### `getAST`
`getAST` returns the root AST node of the collection.
**Example:**
```jsx
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**:
```jsx
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**:
```jsx
const secondVariableDeclaration = j.find(j.VariableDeclaration).at(1);
```
### `getTypes`
`getTypes` returns the set of node types present in the collection.
**Example:**
```jsx
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:**
```jsx
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](https://github.com/facebook/jscodeshift/blob/4851fc8a01036868efb4cf9676f3e97836097376/src/collections/Node.js#L139))
### **`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**:
```jsx
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**:
```jsx
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**:
```jsx
j.find(j.FunctionDeclaration)
.insertAfter(j.expressionStatement(j.stringLiteral('Inserted after')));
```
### **`remove`**
Removes the current node(s).
**Example**:
```jsx
j.find(j.VariableDeclaration).remove();
```
### `renameTo` ([source](https://github.com/facebook/jscodeshift/blob/main/src/collections/VariableDeclarator.js))
`renameTo` renames the nodes in the collection to a new name.
**Parameters:** `newName`: The new name to rename to.
**Example:**
```jsx
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**:
```jsx
const transformedSource = j.toSource({ quote: 'single' });
```