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

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