jscodeshift

Original：🇺🇸 English

Translated

jscodeshift codemod development best practices from Facebook/Meta. This skill should be used when writing, reviewing, or debugging jscodeshift codemods. Triggers on tasks involving AST transformation, code migration, automated refactoring, or codemod development.

28installs

Sourcepproenca/dot-skills

Added on2026-02-04

NPX Install

npx skill4agent add pproenca/dot-skills jscodeshift

SKILL.md Content

View Translation Comparison →

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


parser-
traverse-
filter-
transform-
codegen-
test-
runner-
advanced-

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