0
# Transformer Implementation
1

2
The core transformer that integrates with Parcel's build pipeline to apply Babel transformations to JavaScript, TypeScript, and JSX assets.
3

4
## Capabilities
5

6
### BabelTransformer (Default Export)
7

8
The default export is a Transformer instance (not a class) that implements Parcel's Transformer interface for Babel processing.
9

10
```javascript { .api }
11
/**
12
 * Default export - Babel transformer instance for Parcel
13
 * This is a pre-configured Transformer instance, not a class or constructor
14
 * Implements the complete Transformer interface for Babel compilation
15
 */
16
export default BabelTransformer: Transformer;
17

18
interface Transformer {
19
  loadConfig(options: LoadConfigOptions): Promise<BabelConfigResult | null>;
20
  canReuseAST(options: CanReuseASTOptions): boolean;
21
  transform(options: TransformOptions): Promise<MutableAsset[]>;
22
  generate(options: GenerateOptions): Promise<GenerateResult>;
23
}
24
```
25

26
### Load Configuration
27

28
Loads and validates Babel configuration for the current asset being processed.
29

30
```javascript { .api }
31
/**
32
 * Loads Babel configuration for the current asset
33
 * @param options - Configuration loading options
34
 * @returns Promise resolving to BabelConfigResult or null if no config needed
35
 */
36
loadConfig(options: LoadConfigOptions): Promise<BabelConfigResult | null>;
37

38
interface LoadConfigOptions {
39
  config: Config;
40
  options: PluginOptions;
41
  logger: PluginLogger;
42
}
43
```
44

45
**Usage Example:**
46

47
```javascript
48
// Called internally by Parcel
49
const configResult = await transformer.loadConfig({
50
  config: parcelConfig,
51
  options: pluginOptions,
52
  logger: parcelLogger
53
});
54
```
55

56
### AST Reuse Check
57

58
Determines if an existing AST can be reused for the current transformation.
59

60
```javascript { .api }
61
/**
62
 * Determines if the provided AST can be reused for transformation
63
 * @param options - AST reuse check options
64
 * @returns True if AST can be reused, false otherwise
65
 */
66
canReuseAST(options: CanReuseASTOptions): boolean;
67

68
interface CanReuseASTOptions {
69
  ast: AST;
70
}
71

72
interface AST {
73
  type: string;
74
  version: string;
75
  program: any;
76
}
77
```
78

79
**Implementation Details:**
80
- Returns `true` if AST type is 'babel' and version satisfies '^7.0.0'
81
- Enables performance optimization by reusing compatible ASTs
82

83
### Transform Asset
84

85
Performs the core Babel transformation on JavaScript assets.
86

87
```javascript { .api }
88
/**
89
 * Transforms JavaScript/TypeScript/JSX assets using Babel
90
 * @param options - Transformation options
91
 * @returns Promise resolving to array containing the transformed asset
92
 */
93
transform(options: TransformOptions): Promise<MutableAsset[]>;
94

95
interface TransformOptions {
96
  asset: MutableAsset;
97
  config: BabelConfigResult | null;
98
  logger: PluginLogger;
99
  options: PluginOptions;
100
  tracer: PluginTracer;
101
}
102
```
103

104
**Usage Example:**
105

106
```javascript
107
// Called internally by Parcel
108
const transformedAssets = await transformer.transform({
109
  asset: jsAsset,
110
  config: babelConfig,
111
  logger: parcelLogger,
112
  options: pluginOptions,
113
  tracer: performanceTracer
114
});
115
```
116

117
**Transformation Process:**
118
1. Checks if Babel configuration exists
119
2. Applies additional plugins from asset metadata if present
120
3. Calls `babel7()` function to perform actual transformation
121
4. Enhances any errors with source context
122
5. Returns array containing the single transformed asset
123

124
### Generate Code
125

126
Generates final JavaScript code and source maps from the transformed AST.
127

128
```javascript { .api }
129
/**
130
 * Generates JavaScript code and source maps from Babel AST
131
 * @param options - Code generation options
132
 * @returns Promise resolving to generated code and source map
133
 */
134
generate(options: GenerateOptions): Promise<GenerateResult>;
135

136
interface GenerateOptions {
137
  asset: MutableAsset;
138
  ast: AST;
139
  options: PluginOptions;
140
}
141

142
interface GenerateResult {
143
  content: string;
144
  map: SourceMap;
145
}
146
```
147

148
**Generation Process:**
149
1. Retrieves original source map from asset
150
2. Resolves @babel/core and @babel/generator dependencies
151
3. Generates code using Babel generator with:
152
   - Source file name relative to project root
153
   - Source map generation enabled based on environment
154
   - Comment preservation enabled
155
   - Import attributes using 'with' keyword
156
4. Creates new SourceMap and adds index mappings
157
5. Copies source content from original map if available
158

159
**Usage Example:**
160

161
```javascript
162
// Called internally by Parcel during code generation phase
163
const result = await transformer.generate({
164
  asset: processedAsset,
165
  ast: babelAST,
166
  options: pluginOptions
167
});
168

169
console.log(result.content); // Generated JavaScript code
170
console.log(result.map); // Source map for debugging
171
```
172

173
## Error Handling
174

175
The transformer includes comprehensive error handling:
176

177
- **Configuration Errors**: Invalid or problematic Babel configurations
178
- **Transformation Errors**: Babel compilation failures with enhanced context
179
- **Dependency Errors**: Missing or incompatible Babel dependencies
180
- **AST Errors**: Invalid or incompatible AST structures
181

182
All errors are enhanced with source context using the `babelErrorEnhancer` function before being thrown.
183

184
## Performance Considerations
185

186
- **AST Reuse**: Checks for compatible ASTs to avoid re-parsing
187
- **Dependency Caching**: Resolves and caches Babel dependencies
188
- **Source Map Optimization**: Efficient source map generation and copying
189
- **Configuration Warnings**: Alerts about performance-impacting configurations