Jscodeshift

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