jscodeshift

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Facebook/Meta jscodeshift Best Practices

Facebook/Meta jscodeshift 最佳实践

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.

本指南为AI Agent和大语言模型（LLM）提供了jscodeshift codemod开发的全面最佳实践，包含8个类别共40条规则，按影响优先级排序，从关键规则（解析器配置、AST遍历）到进阶规则（高级模式）。每条规则都配有详细说明、真实示例和具体影响指标。

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

在以下场景中参考本指南：

为代码迁移编写新的jscodeshift codemod
调试转换失败或异常行为
优化codemod在大型代码库中的性能
审查codemod代码的正确性
测试codemod的边缘情况和回归问题

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-`


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

优先级	类别	影响程度	前缀
1	解析器配置	关键（CRITICAL）	`parser-`
2	AST遍历模式	关键（CRITICAL）	`traverse-`
3	节点过滤	高（HIGH）	`filter-`
4	AST转换	高（HIGH）	`transform-`
5	代码生成	中（MEDIUM）	`codegen-`
6	测试策略	中（MEDIUM）	`test-`
7	运行器优化	低-中（LOW-MEDIUM）	`runner-`
8	高级模式	低（LOW）	`advanced-`

Quick Reference

快速参考

1. Parser Configuration (CRITICAL)

1. 解析器配置（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

```
parser-typescript-config
```
- 为TypeScript文件使用正确的解析器
```
parser-flow-annotation
```
- 为Flow类型标注的代码使用Flow解析器
```
parser-babel5-compat
```
- 现代语法避免使用默认的babel5compat解析器
```
parser-export-declaration
```
- 从转换模块中导出解析器配置
```
parser-astexplorer-match
```
- 保持AST Explorer解析器与jscodeshift解析器一致

2. AST Traversal Patterns (CRITICAL)

2. AST遍历模式（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

```
traverse-find-specific-type
```
- 在find()调用中使用特定的节点类型
```
traverse-two-pass-pattern
```
- 复杂转换使用两次遍历模式
```
traverse-early-return
```
- 无需转换时提前返回
```
traverse-find-filter-pattern
```
- 优先使用带过滤对象的find()而非链式filter()调用
```
traverse-closest-scope
```
- 依赖作用域的转换使用closestScope()
```
traverse-avoid-repeated-find
```
- 避免对同一节点类型重复调用find()

3. Node Filtering (HIGH)

3. 节点过滤（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

```
filter-path-parent-check
```
- 转换前检查父节点路径
```
filter-import-binding
```
- 跟踪导入绑定以准确检测使用情况
```
filter-nullish-checks
```
- 属性访问前添加空值检查
```
filter-jsx-context
```
- 区分JSX上下文与常规JavaScript
```
filter-computed-properties
```
- 过滤中处理计算属性键

4. AST Transformation (HIGH)

4. AST转换（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

```
transform-builder-api
```
- 使用Builder API创建AST节点
```
transform-replacewith-callback
```
- 依赖上下文的转换使用replaceWith回调
```
transform-insert-import
```
- 在正确位置插入导入语句
```
transform-preserve-comments
```
- 替换节点时保留注释
```
transform-renameto
```
- 变量重命名使用renameTo方法
```
transform-remove-unused-imports
```
- 转换后移除未使用的导入

5. Code Generation (MEDIUM)

5. 代码生成（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

```
codegen-tosource-options
```
- 配置toSource()以保证格式一致
```
codegen-preserve-style
```
- 使用recast保留原始代码风格
```
codegen-template-literals
```
- 复杂节点创建使用模板字符串
```
codegen-print-width
```
- 为长代码行设置合适的打印宽度

6. Testing Strategies (MEDIUM)

6. 测试策略（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

```
test-inline-snapshots
```
- 使用defineInlineTest验证输入输出
```
test-negative-cases
```
- 优先编写负面测试用例
```
test-dry-run-exploration
```
- 使用试运行模式探索代码库
```
test-fixture-files
```
- 复杂测试用例使用测试夹具文件
```
test-parse-errors
```
- 测试解析错误的处理逻辑

7. Runner Optimization (LOW-MEDIUM)

7. 运行器优化（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

```
runner-parallel-workers
```
- 配置工作线程数以优化并行处理
```
runner-ignore-patterns
```
- 使用忽略模式跳过非源码文件
```
runner-extensions-filter
```
- 按文件扩展名过滤文件
```
runner-batch-processing
```
- 大型代码库分批处理
```
runner-verbose-output
```
- 调试转换时使用详细输出

8. Advanced Patterns (LOW)

8. 高级模式（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

```
advanced-compose-transforms
```
- 将多个转换组合为流水线
```
advanced-scope-analysis
```
- 使用作用域分析实现安全的变量转换
```
advanced-multi-file-state
```
- 通过选项在多文件间共享状态
```
advanced-custom-collections
```
- 创建自定义集合方法

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.

如需包含所有规则的综合文档，请查看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

文件	描述
AGENTS.md	包含所有规则的完整编译指南
references/_sections.md	类别定义与排序说明
assets/templates/_template.md	新规则模板
metadata.json	版本与参考信息