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 |