# jscodeshift — AST-Based JavaScript Codemod Toolkit by Meta

> jscodeshift is a toolkit for running codemods over JavaScript and TypeScript files, providing a jQuery-like API for searching and transforming abstract syntax trees at scale across entire codebases.

## Install

Save as a script file and run:

# jscodeshift — AST-Based JavaScript Codemod Toolkit by Meta

## Quick Use
```bash
# Install globally
npm install -g jscodeshift

# Run a codemod transform on a directory
jscodeshift -t my-transform.js src/

# Run with TypeScript parser
jscodeshift --parser tsx -t transform.ts src/
```

## Introduction
jscodeshift is Meta's toolkit for writing and running codemods — automated code transformations that modify source files by manipulating abstract syntax trees rather than text. It wraps the recast printer to preserve formatting and provides a chainable API that makes large-scale refactors safe, repeatable, and reviewable.

## What jscodeshift Does
- Parses JavaScript and TypeScript files into ASTs using babel or TypeScript parsers
- Provides a jQuery-inspired API for finding, filtering, and replacing AST nodes
- Preserves original formatting and whitespace through the recast pretty-printer
- Runs transforms in parallel across thousands of files using worker processes
- Supports dry-run mode to preview changes before writing them to disk

## Architecture Overview
jscodeshift reads source files, parses them into ASTs via configurable parsers (babel, flow, ts, tsx), and passes each AST to a user-defined transform function. The transform uses the Collection API to query and modify nodes. After transformation, recast reprints the modified AST back to source, preserving untouched code exactly as written. A runner coordinates parallel execution across files using Node.js worker threads.

## Self-Hosting & Configuration
- Install locally per project: `npm install --save-dev jscodeshift`
- Write transforms as CommonJS or ES modules exporting a function that receives `(fileInfo, api, options)`
- Use `--parser babel` for modern JS or `--parser tsx` for TypeScript and JSX files
- Pass custom options to transforms via `--key=value` flags on the CLI
- Configure `.jscodeshift.config.js` for default parser and extension settings

## Key Features
- jQuery-like chainable API: `root.find(j.CallExpression).filter(...).replaceWith(...)`
- Format-preserving output that only changes lines touched by the transform
- Built-in test utilities for writing unit tests against transform functions
- Parallel file processing for fast execution on large codebases
- Extensible parser support for Flow, TypeScript, and JSX

## Comparison with Similar Tools
- **ts-morph** — TypeScript-specific with compiler API access; jscodeshift works across JS and TS with broader parser support
- **Babel plugins** — Transform during build; jscodeshift runs as a one-time migration tool
- **comby** — Language-agnostic structural matching; jscodeshift provides full AST manipulation for JS/TS
- **ast-grep** — Rust-based with pattern matching syntax; jscodeshift offers a programmatic API for complex logic
- **ESLint with --fix** — Rule-based fixes; jscodeshift handles arbitrary multi-node transformations

## FAQ
**Q: When should I use jscodeshift instead of find-and-replace?**
A: Use jscodeshift when the change depends on code structure — renaming a function only when called with certain arguments, updating import paths conditionally, or restructuring object patterns.

**Q: Can I test my codemod before running it?**
A: Yes. jscodeshift provides `defineTest` and `defineInlineTest` utilities that compare input/output fixture files to verify your transform produces correct results.

**Q: Does jscodeshift modify files in place?**
A: By default yes. Use `--dry` to preview changes without writing, or `--print` to output transformed code to stdout instead.

**Q: How do I handle files that fail to parse?**
A: jscodeshift logs parse errors and skips those files. You can also specify `--ignore-pattern` to exclude files that use unsupported syntax.

## Sources
- https://github.com/facebook/jscodeshift
- https://github.com/facebook/jscodeshift/wiki/jscodeshift-Documentation

---
Source: https://tokrepo.com/en/workflows/asset-af0ddab5
Author: Script Depot