jscodeshift

A toolkit for JavaScript codemods

weekly downloads5.6M

versionv17.3.0

licenseMIT

categorytoolchain

codemodrecastbabel

Overview

jscodeshift is a toolkit for running codemods—automated scripts that transform JavaScript and TypeScript codebases by manipulating the Abstract Syntax Tree (AST). Instead of fragile find-and-replace operations, jscodeshift understands code structure, enabling reliable refactors across hundreds or thousands of files. It's built on top of recast (for parsing and printing with preserved formatting) and ast-types (for node manipulation), exposing a chainable, collection-based API inspired by jQuery.

The package was created by Facebook engineers to solve a critical problem: safely migrating large codebases when APIs change or coding patterns evolve. With over 5.6 million weekly downloads, it's widely adopted by library maintainers who provide codemods to help users upgrade between major versions, and by engineering teams performing architectural refactors. The tool excels at semantic transformations like renaming imports, converting function signatures, or updating deprecated patterns—tasks where regex-based tools fail.

jscodeshift transforms operate on collections of AST nodes called NodePaths, which wrap nodes with traversal context. You write a transform function that receives file content and the jscodeshift API, queries the AST using methods like .find() and .filter(), applies mutations with .replaceWith() or .remove(), then outputs the modified source. The CLI runner executes transforms in parallel across multiple files, with options for dry-runs, custom parsers (Babel for modern syntax, TypeScript for .ts files), and detailed logging.

Developers choose jscodeshift when they need surgical precision in code changes with minimal diff noise. Because it preserves original formatting (whitespace, comments, semicolon style), generated pull requests remain readable. The semantic approach means you can confidently rename a variable without accidentally changing string literals or comments that happen to contain the same text—a guarantee impossible with text-based tools.

Quick Start

typescript

const transform = (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  root
    .find(j.ImportDeclaration, {
      source: { value: 'lodash' }
    })
    .forEach(path => {
      const specifiers = path.value.specifiers.filter(spec => {
        return spec.imported && spec.imported.name === 'map';
      });
      
      if (specifiers.length > 0) {
        j(path).replaceWith(
          j.importDeclaration(
            [j.importDefaultSpecifier(j.identifier('map'))],
            j.literal('lodash/map')
          )
        );
      }
    });

  root
    .find(j.CallExpression, {
      callee: { name: 'map' }
    })
    .filter(path => {
      const args = path.value.arguments;
      return args.length === 2 && args[0].type === 'ArrayExpression';
    })
    .forEach(path => {
      const [array, callback] = path.value.arguments;
      j(path).replaceWith(
        j.callExpression(
          j.memberExpression(array, j.identifier('map')),
          [callback]
        )
      );
    });

  return root.toSource();
};

module.exports = transform;

Use Cases

Library migration codemods: When React released Hooks, maintainers published jscodeshift transforms to convert class components to functional components automatically. You can distribute transforms with your library to upgrade user code between breaking versions, reducing migration friction.

API deprecation and replacement: If your team deprecates fetchData() in favor of loadData() across 200 components, a codemod can update all call sites, adjust import statements, and even transform callback patterns to promises—changes that would take days manually and risk human error.

Code standardization: Enforce architectural patterns by transforming non-compliant code. Convert all default exports to named exports, wrap class methods with error boundaries, or add TypeScript type annotations to untyped functions based on runtime usage patterns.

Framework upgrades: When Next.js or Vue release major versions with changed APIs, codemods handle repetitive transformations like updating page component structures, converting route definitions, or adapting data-fetching methods across entire applications.

Refactoring legacy code: Convert callbacks to async/await throughout a codebase, replace var with const/let intelligently based on reassignment analysis, or modernize module systems from CommonJS to ES6 imports—transformations that preserve behavior while updating syntax.

Pros & Cons

Pros

+Semantic understanding prevents false positives that plague regex-based refactoring; distinguishes between variable names and strings containing the same text
+Preserves original code formatting, comments, and whitespace, generating minimal diffs that are easy to review and merge
+jQuery-like collection API lowers learning curve compared to raw AST manipulation; chainable methods feel familiar to JavaScript developers
+Built-in parallel execution handles large codebases efficiently; CLI provides dry-run, multiple parser support, and granular control
+Battle-tested by Facebook and major open-source projects; extensive ecosystem of community transforms for common migrations

Cons

−Steep learning curve for AST concepts; requires understanding node types, paths, and tree traversal patterns before writing effective transforms
−Debugging transforms is challenging—no step-through debugger for AST operations, relying on console logging and small test files
−Parser limitations can cause failures on edge-case syntax or experimental features; choosing the wrong parser (babel vs tsx vs flow) leads to parse errors
−Performance degrades on extremely large files (>10k lines); parallel execution helps but individual file processing can be slow
−Limited TypeScript type inference in transforms; the API is JavaScript-first, making it harder to leverage type information during refactoring

Alternatives

ts-morphv27.0.2

TypeScript compiler wrapper for static analysis and code manipulation.

toolchaintypescriptast

8.8M / week

Install

bash

npm install jscodeshift

bash

pnpm add jscodeshift

bash

bun add jscodeshift

Overview

Quick Start

typescript

const transform = (fileInfo, api) => {
  const j = api.jscodeshift;
  const root = j(fileInfo.source);

  root
    .find(j.ImportDeclaration, {
      source: { value: 'lodash' }
    })
    .forEach(path => {
      const specifiers = path.value.specifiers.filter(spec => {
        return spec.imported && spec.imported.name === 'map';
      });
      
      if (specifiers.length > 0) {
        j(path).replaceWith(
          j.importDeclaration(
            [j.importDefaultSpecifier(j.identifier('map'))],
            j.literal('lodash/map')
          )
        );
      }
    });

  root
    .find(j.CallExpression, {
      callee: { name: 'map' }
    })
    .filter(path => {
      const args = path.value.arguments;
      return args.length === 2 && args[0].type === 'ArrayExpression';
    })
    .forEach(path => {
      const [array, callback] = path.value.arguments;
      j(path).replaceWith(
        j.callExpression(
          j.memberExpression(array, j.identifier('map')),
          [callback]
        )
      );
    });

  return root.toSource();
};

module.exports = transform;

Use Cases

Pros & Cons

Pros

+Semantic understanding prevents false positives that plague regex-based refactoring; distinguishes between variable names and strings containing the same text
+Preserves original code formatting, comments, and whitespace, generating minimal diffs that are easy to review and merge
+jQuery-like collection API lowers learning curve compared to raw AST manipulation; chainable methods feel familiar to JavaScript developers
+Built-in parallel execution handles large codebases efficiently; CLI provides dry-run, multiple parser support, and granular control
+Battle-tested by Facebook and major open-source projects; extensive ecosystem of community transforms for common migrations

Cons

−Steep learning curve for AST concepts; requires understanding node types, paths, and tree traversal patterns before writing effective transforms
−Debugging transforms is challenging—no step-through debugger for AST operations, relying on console logging and small test files
−Parser limitations can cause failures on edge-case syntax or experimental features; choosing the wrong parser (babel vs tsx vs flow) leads to parse errors
−Performance degrades on extremely large files (>10k lines); parallel execution helps but individual file processing can be slow
−Limited TypeScript type inference in transforms; the API is JavaScript-first, making it harder to leverage type information during refactoring