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 Priority Category Impact Prefix 1 Parser Configuration CRITICAL parser- 2 AST Traversal Patterns CRITICAL traverse- 3 Node Filtering HIGH filter- 4 AST Transformation HIGH transform- 5 Code Generation MEDIUM codegen- 6 Testing Strategies MEDIUM test- 7 Runner Optimization LOW-MEDIUM runner- 8 Advanced Patterns LOW 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 File Description AGENTS.md Complete compiled guide with all rules references/_sections.md Category definitions and ordering assets/templates/_template.md Template for new rules metadata.json Version and reference information