Facebook/Meta jscodeshift Best Practices

Comprehensive best practices guide for jscodeshift codemod development, designed for AI agents and LLMs. Contains 40 rules across 8 categories, prioritized by impact from critical (parser configuration, AST traversal) to incremental (advanced patterns). Each rule includes detailed explanations, real-world examples, and specific impact metrics.

When to Apply

Reference these guidelines when:

• Writing new jscodeshift codemods for code migrations
• Debugging transform failures or unexpected behavior
• Optimizing codemod performance on large codebases
• Reviewing codemod code for correctness
• Testing codemods for edge cases and regressions

Rule Categories by Priority

parser-

traverse-

filter-

transform-

codegen-

test-

runner-

advanced-

Quick Reference

1. Parser Configuration (CRITICAL)

• parser-typescript-config

  - Use correct parser for TypeScript files

• parser-flow-annotation

  - Use Flow parser for Flow-typed code

• parser-babel5-compat

  - Avoid default babel5compat for modern syntax

• parser-export-declaration

  - Export parser from transform module

• parser-astexplorer-match

  - Match AST Explorer parser to jscodeshift parser

2. AST Traversal Patterns (CRITICAL)

• traverse-find-specific-type

  - Use specific node types in find() calls

• traverse-two-pass-pattern

  - Use two-pass pattern for complex transforms

• traverse-early-return

  - Return early when no transformation needed

• traverse-find-filter-pattern

  - Use find() with filter object over filter() chain

• traverse-closest-scope

  - Use closestScope() for scope-aware transforms

• traverse-avoid-repeated-find

  - Avoid repeated find() calls for same node type

3. Node Filtering (HIGH)

• filter-path-parent-check

  - Check parent path before transformation

• filter-import-binding

  - Track import bindings for accurate usage detection

• filter-nullish-checks

  - Add nullish checks before property access

• filter-jsx-context

  - Distinguish JSX context from regular JavaScript

• filter-computed-properties

  - Handle computed property keys in filters

4. AST Transformation (HIGH)

• transform-builder-api

  - Use builder API for creating AST nodes

• transform-replacewith-callback

  - Use replaceWith callback for context-aware transforms

• transform-insert-import

  - Insert imports at correct position

• transform-preserve-comments

  - Preserve comments when replacing nodes

• transform-renameto

  - Use renameTo for variable renaming

• transform-remove-unused-imports

  - Remove unused imports after transformation

5. Code Generation (MEDIUM)

• codegen-tosource-options

  - Configure toSource() for consistent formatting

• codegen-preserve-style

  - Preserve original code style with recast

• codegen-template-literals

  - Use template literals for complex node creation

• codegen-print-width

  - Set appropriate print width for long lines

6. Testing Strategies (MEDIUM)

• test-inline-snapshots

  - Use defineInlineTest for input/output verification

• test-negative-cases

  - Write negative test cases first

• test-dry-run-exploration

  - Use dry run mode for codebase exploration

• test-fixture-files

  - Use fixture files for complex test cases

• test-parse-errors

  - Test for parse error handling

7. Runner Optimization (LOW-MEDIUM)

• runner-parallel-workers

  - Configure worker count for optimal parallelization

• runner-ignore-patterns

  - Use ignore patterns to skip non-source files

• runner-extensions-filter

  - Filter files by extension

• runner-batch-processing

  - Process large codebases in batches

• runner-verbose-output

  - Use verbose output for debugging transforms

8. Advanced Patterns (LOW)

• advanced-compose-transforms

  - Compose multiple transforms into pipelines

• advanced-scope-analysis

  - Use scope analysis for safe variable transforms

• advanced-multi-file-state

  - Share state across files with options

• advanced-custom-collections

  - Create custom collection methods

How to Use

Read individual reference files for detailed explanations and code examples:

• Section definitions - Category structure and impact levels
• Rule template - Template for adding new rules

Full Compiled Document

For a single comprehensive document containing all rules, see AGENTS.md.

Reference Files