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](references/parser-typescript-config.md) - Use correct parser for TypeScript files
• [parser-flow-annotation](references/parser-flow-annotation.md) - Use Flow parser for Flow-typed code
• [parser-babel5-compat](references/parser-babel5-compat.md) - Avoid default babel5compat for modern syntax
• [parser-export-declaration](references/parser-export-declaration.md) - Export parser from transform module
• [parser-astexplorer-match](references/parser-astexplorer-match.md) - Match AST Explorer parser to jscodeshift parser

2. AST Traversal Patterns (CRITICAL)

• [traverse-find-specific-type](references/traverse-find-specific-type.md) - Use specific node types in find() calls
• [traverse-two-pass-pattern](references/traverse-two-pass-pattern.md) - Use two-pass pattern for complex transforms
• [traverse-early-return](references/traverse-early-return.md) - Return early when no transformation needed
• [traverse-find-filter-pattern](references/traverse-find-filter-pattern.md) - Use find() with filter object over filter() chain
• [traverse-closest-scope](references/traverse-closest-scope.md) - Use closestScope() for scope-aware transforms
• [traverse-avoid-repeated-find](references/traverse-avoid-repeated-find.md) - Avoid repeated find() calls for same node type

3. Node Filtering (HIGH)

• [filter-path-parent-check](references/filter-path-parent-check.md) - Check parent path before transformation
• [filter-import-binding](references/filter-import-binding.md) - Track import bindings for accurate usage detection
• [filter-nullish-checks](references/filter-nullish-checks.md) - Add nullish checks before property access
• [filter-jsx-context](references/filter-jsx-context.md) - Distinguish JSX context from regular JavaScript
• [filter-computed-properties](references/filter-computed-properties.md) - Handle computed property keys in filters

4. AST Transformation (HIGH)

• [transform-builder-api](references/transform-builder-api.md) - Use builder API for creating AST nodes
• [transform-replacewith-callback](references/transform-replacewith-callback.md) - Use replaceWith callback for context-aware transforms
• [transform-insert-import](references/transform-insert-import.md) - Insert imports at correct position
• [transform-preserve-comments](references/transform-preserve-comments.md) - Preserve comments when replacing nodes
• [transform-renameto](references/transform-renameto.md) - Use renameTo for variable renaming
• [transform-remove-unused-imports](references/transform-remove-unused-imports.md) - Remove unused imports after transformation

5. Code Generation (MEDIUM)

• [codegen-tosource-options](references/codegen-tosource-options.md) - Configure toSource() for consistent formatting
• [codegen-preserve-style](references/codegen-preserve-style.md) - Preserve original code style with recast
• [codegen-template-literals](references/codegen-template-literals.md) - Use template literals for complex node creation
• [codegen-print-width](references/codegen-print-width.md) - Set appropriate print width for long lines

6. Testing Strategies (MEDIUM)

• [test-inline-snapshots](references/test-inline-snapshots.md) - Use defineInlineTest for input/output verification
• [test-negative-cases](references/test-negative-cases.md) - Write negative test cases first
• [test-dry-run-exploration](references/test-dry-run-exploration.md) - Use dry run mode for codebase exploration
• [test-fixture-files](references/test-fixture-files.md) - Use fixture files for complex test cases
• [test-parse-errors](references/test-parse-errors.md) - Test for parse error handling

7. Runner Optimization (LOW-MEDIUM)

• [runner-parallel-workers](references/runner-parallel-workers.md) - Configure worker count for optimal parallelization
• [runner-ignore-patterns](references/runner-ignore-patterns.md) - Use ignore patterns to skip non-source files
• [runner-extensions-filter](references/runner-extensions-filter.md) - Filter files by extension
• [runner-batch-processing](references/runner-batch-processing.md) - Process large codebases in batches
• [runner-verbose-output](references/runner-verbose-output.md) - Use verbose output for debugging transforms

8. Advanced Patterns (LOW)

• [advanced-compose-transforms](references/advanced-compose-transforms.md) - Compose multiple transforms into pipelines
• [advanced-scope-analysis](references/advanced-scope-analysis.md) - Use scope analysis for safe variable transforms
• [advanced-multi-file-state](references/advanced-multi-file-state.md) - Share state across files with options
• [advanced-custom-collections](references/advanced-custom-collections.md) - Create custom collection methods

How to Use

Read individual reference files for detailed explanations and code examples:

• [Section definitions](references/_sections.md) - Category structure and impact levels
• [Rule template](assets/templates/_template.md) - Template for adding new rules

Full Compiled Document

For a single comprehensive document containing all rules, see [AGENTS.md](AGENTS.md).

Reference Files