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 | 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`](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 | File | Description | |------|-------------| | [AGENTS.md](AGENTS.md) | Complete compiled guide with all rules | | [references/_sections.md](references/_sections.md) | Category definitions and ordering | | [assets/templates/_template.md](assets/templates/_template.md) | Template for new rules | | [metadata.json](metadata.json) | Version and reference information |