jscodeshift

library17.3.0jsnpmunverified

jscodeshift is a powerful toolkit for automating code transformations (codemods) across JavaScript and TypeScript projects. It operates by parsing source code into an Abstract Syntax Tree (AST), allowing programmatic manipulation, and then printing the modified AST back into code. The current stable version is 17.3.0, released in early 2026. While lacking a fixed release cadence, the project is actively maintained, with frequent minor and patch updates primarily driven by `recast` dependency bumps to support new language features (e.g., recent TypeScript syntax) and address parsing quirks. A significant version jump from `v0.x` to `v17.0.0` occurred in August 2024, signaling its maturity rather than a traditional `1.0` release. Its core strength lies in its tight integration with `recast`, which excels at preserving original code formatting, comments, and whitespace, minimizing disruption to a codebase's aesthetics during large-scale refactors. It offers a robust CLI runner for applying transforms to files and an intuitive API for writing complex, style-preserving codemods.

devops testing

npm install jscodeshift

github ↗package ↗

INSTALL

IMPORT

SIG · JSCODESHIFT

jscodeshift

devopsjavascriptv17.3.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

transformer

✓ export default function transformer(fileInfo: FileInfo, api: API, options: Options): string | null { /* ... */ }

A jscodeshift transform file exports a default function. `fileInfo` contains the source code, `api` provides the `j` (jscodeshift AST builder) and `g` (recast utility) objects, and `options` holds CLI arguments passed to the transform.

j (jscodeshift API)

✓ const j = api.j;

✗ import j from 'jscodeshift';

The jscodeshift API, aliased as `j`, is an instance of `recast.types.builders` and is provided as part of the `api` object within the transform function, not directly imported from the package root.

runTransform

✓ import { runTransform } from 'jscodeshift/testUtils';

✗ import { runTransform } from 'jscodeshift';

Utilities for testing codemods, such as `runTransform`, are exposed from the `jscodeshift/testUtils` subpath rather than directly from the main package entry point.

FileInfo, API, Options (types)

✓ import type { API, FileInfo, Options } from 'jscodeshift';

✗ import { API, FileInfo, Options } from 'jscodeshift';

For TypeScript projects, it is best practice to import these types using `import type` to clearly distinguish them from runtime values and prevent potential bundling issues.

This TypeScript quickstart demonstrates a basic codemod that updates `var` declarations to `let` or `const` based on a simplistic immutability check, then shows how to execute it via the `jscodeshift` CLI.

// transform.ts import type { API, FileInfo, Options } from 'jscodeshift'; /** * A simple codemod that transforms `var` declarations to `let` or `const`. * It will use `const` if all declarators are simple literals, otherwise `let`. */ export default function transformer(file: FileInfo, api: API, options: Options): string | null { const j = api.j; const root = j(file.source); let changed = false; root .find(j.VariableDeclaration, { kind: 'var' }) .forEach((path) => { const declarations = path.node.declarations; // A simplistic check to determine if all declarations are immutable literals const allAreConstants = declarations.every(decl => j.match(decl, { id: j.Identifier, init: j.Literal }) && decl.init !== null ); if (allAreConstants) { path.node.kind = 'const'; } else { path.node.kind = 'let'; } changed = true; }); // Only return the source if changes were made, otherwise return null return changed ? root.toSource() : null; } // To run this codemod on a file named `my-code.js`: // 1. Save the above code as `transform.ts`. // 2. Ensure `jscodeshift` is installed globally or locally. // `npm install -g jscodeshift` // 3. Execute the codemod: // `jscodeshift -t ./transform.ts ./my-code.js --parser=ts`

jscodeshift --version

Debug

Known issues

breakingjscodeshift v17.0.0 and above explicitly require Node.js version 16 or higher. Earlier versions of Node.js are no longer supported.

fix

Upgrade your Node.js environment to version 16 or newer. Use `nvm install 16 && nvm use 16` or similar version management tools.

affects: >=17.0.0

breakingThe package underwent a significant major version bump from `0.x.x` to `17.0.0`. This jump was a deliberate choice to reflect the project's maturity after nine years, similar to how React transitioned from v0.14 to v15.0, rather than a traditional v1.0.0 release. While the core API largely remained stable, this indicates a new major release branch.

fix

Review the changelog for any specific breaking changes (e.g., Node.js version requirement) beyond the version number itself when upgrading from pre-v17 versions.

affects: =17.0.0

breakingVersions of `jscodeshift` up to `0.13.0` depended on the `colors` package, which was subject to a critical security vulnerability (supply chain attack) in version `1.4.1`.

fix

Immediately upgrade `jscodeshift` to version `0.13.1` or higher, which replaced `colors` with `chalk`, mitigating the vulnerability.

affects: <=0.13.0

gotchaIncorrect or missing parser configuration is a common source of errors when running codemods, especially with TypeScript or JSX files.

fix

Always specify the appropriate parser using the `--parser` CLI option (e.g., `--parser=ts` for TypeScript, `--parser=tsx` for TSX/JSX, `--parser=flow` for Flow). For custom Babel/Flow configurations, use `--parser-config` pointing to a JSON file.

affects: *

gotchajscodeshift, via `recast`, prioritizes preserving the original code's style, including formatting, comments, and whitespace. While beneficial, this means it will not automatically reformat your code to a new style guide or apply a linter's autofixes.

fix

If a strict code style or reformatting is required after running a codemod, consider integrating a separate formatting step (e.g., Prettier or ESLint with `--fix`) into your workflow after the codemod execution.

affects: *

Errors

Common errors & fixes

Error: SyntaxError: Unknown word (1:0) (or similar parser error like Unexpected token)

The jscodeshift runner failed to parse the source file, typically due to an incorrect or missing parser setting for the file's language features (e.g., TypeScript, JSX).

fix

Specify the correct parser via the CLI, for example: `jscodeshift -t transform.js my-file.ts --parser=ts` or `--parser=tsx` for JSX/TSX. Use `--parser-config` for custom Babel/Flow configurations.

Error: The transform function must return a string or null.

The default exported transform function in your codemod file did not return either the modified source code (as a string) or `null` (if no changes were made).

fix

Ensure your `export default function transformer(...)` always returns `root.toSource()` after modifications, or `null` if the file should not be changed.

Error: Cannot find module 'jscodeshift/testUtils'

An attempt was made to import utilities from `jscodeshift/testUtils` (or other subpaths) with an incorrect path or when the module is not accessible.

fix

Verify the exact import path. Ensure `jscodeshift` is installed and the subpath `jscodeshift/testUtils` is correctly resolved by your module resolver. This typically occurs in test files.

ReferenceError: j is not defined

The `j` object, which provides the jscodeshift AST API, was used outside the scope of the transform function where it is passed as `api.j`.

fix

Access the jscodeshift API through the `api` object provided to your transform function: `export default function transformer(fileInfo, api) { const j = api.j; /* ... */ }`.

Upgrade

Version history

17.3.0latest on npm

Audit

Dependencies

@babel/preset-envoptionalPeer dependency, typically needed if your codemod or the files it processes rely on Babel's environment presets for parsing or transformation.

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/facebook/jscodeshift ↗

packagehttps://www.npmjs.com/package/jscodeshift ↗