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