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