0
# Error Handling
1

2
Enhanced error reporting and diagnostics for Babel compilation errors with source context and improved developer experience.
3

4
## Capabilities
5

6
### Babel Error Enhancement
7

8
Enhances Babel compilation errors with additional context and source information for better debugging experience.
9

10
```javascript { .api }
11
/**
12
 * Enhances Babel errors with source context and file information
13
 * Improves error messages by removing redundant path information and adding source code
14
 * @param error - The original Babel error
15
 * @param asset - The asset being processed when the error occurred
16
 * @returns Promise resolving to enhanced error with additional context
17
 */
18
export async function babelErrorEnhancer(
19
  error: BabelError,
20
  asset: BaseAsset
21
): Promise<BabelError>;
22

23
interface BabelError extends Error {
24
  loc?: {
25
    line: number;     // Line number where error occurred
26
    column: number;   // Column number where error occurred
27
  };
28
  source?: string;    // Source code content (added by enhancer)
29
  filePath?: string;  // File path where error occurred (added by enhancer)
30
}
31
```
32

33
### Error Message Cleaning
34

35
The enhancer improves error message readability by removing redundant information:
36

37
```javascript { .api }
38
// Error message processing logic
39
if (error.loc) {
40
  // Remove file path prefix if present to avoid duplication
41
  let start = error.message.startsWith(asset.filePath)
42
    ? asset.filePath.length + 1  // Skip path and separator
43
    : 0;
44
  
45
  // Extract clean error message (first line only)
46
  error.message = error.message.slice(start).split('\n')[0].trim();
47
}
48
```
49

50
**Before Enhancement:**
51
```
52
/path/to/project/src/components/Button.jsx: Unexpected token, expected "}" (15:8)
53
```
54

55
**After Enhancement:**
56
```
57
Unexpected token, expected "}"
58
```
59

60
### Source Context Addition
61

62
Adds complete source code and file path information for enhanced debugging:
63

64
```javascript { .api }
65
// Source context enhancement
66
error.source = await asset.getCode();    // Full source code content
67
error.filePath = asset.filePath;         // Absolute file path
68
```
69

70
This allows error reporting tools and IDEs to:
71
- Display source code context around the error
72
- Provide accurate file navigation
73
- Enable precise error highlighting
74
- Support better stack trace generation
75

76
## Error Types and Common Scenarios
77

78
### Syntax Errors
79

80
Common JavaScript/TypeScript/JSX syntax errors enhanced with source context:
81

82
```javascript
83
// Example: Missing closing brace
84
const Component = () => {
85
  return <div>Hello World</div>
86
  // Missing closing brace causes Babel error
87
```
88

89
**Enhanced Error Information:**
90
- **Message**: "Unexpected token, expected '}'"
91
- **Location**: `{ line: 3, column: 1 }`
92
- **Source**: Complete file content
93
- **FilePath**: Absolute path to component file
94

95
### Transform Plugin Errors
96

97
Errors from Babel plugins during transformation:
98

99
```javascript
100
// Example: TypeScript transformation error
101
interface Props {
102
  invalid syntax here
103
}
104
```
105

106
**Enhanced Error Information:**
107
- **Message**: "Unexpected token"
108
- **Location**: Line and column of syntax error
109
- **Source**: Full TypeScript source
110
- **FilePath**: Path to TypeScript file
111

112
### Configuration Errors
113

114
Errors related to Babel configuration or plugin setup:
115

116
```javascript
117
// Example: Invalid preset configuration
118
{
119
  "presets": [
120
    ["@babel/preset-env", { invalidOption: true }]
121
  ]
122
}
123
```
124

125
**Enhanced Error Information:**
126
- **Message**: "Unknown option: invalidOption"
127
- **Location**: May not have specific location
128
- **Source**: Configuration file content or processed source
129
- **FilePath**: Path to file being processed
130

131
## Integration with Parcel Error System
132

133
The enhanced errors integrate seamlessly with Parcel's diagnostic system:
134

135
```javascript { .api }
136
// Usage in transformer
137
try {
138
  await babel7({
139
    asset,
140
    options,
141
    logger,
142
    babelOptions: config,
143
    tracer
144
  });
145
} catch (error) {
146
  // Enhance error before throwing
147
  throw await babelErrorEnhancer(error, asset);
148
}
149
```
150

151
### Error Enhancement Process
152

153
1. **Error Interception**: Catch original Babel error
154
2. **Message Cleaning**: Remove redundant path information
155
3. **Source Addition**: Add complete source code context
156
4. **Path Addition**: Add absolute file path for navigation
157
5. **Error Propagation**: Re-throw enhanced error for Parcel handling
158

159
## Error Context Examples
160

161
### Before Enhancement
162

163
```javascript
164
// Original Babel error
165
{
166
  name: 'SyntaxError',
167
  message: '/Users/dev/project/src/Button.jsx: Unexpected token (15:8)\n\n  13 |   return (\n  14 |     <div className="button"\n> 15 |       onClick={handleClick\n     |                        ^\n  16 |     >\n  17 |       {children}\n  18 |     </div>',
168
  loc: { line: 15, column: 8 }
169
}
170
```
171

172
### After Enhancement
173

174
```javascript
175
// Enhanced error with context
176
{
177
  name: 'SyntaxError',
178
  message: 'Unexpected token',
179
  loc: { line: 15, column: 8 },
180
  source: 'import React from "react";\n\nconst Button = ({ onClick, children }) => {\n  const handleClick = () => {\n    onClick?.();\n  };\n\n  return (\n    <div className="button"\n      onClick={handleClick\n    >\n      {children}\n    </div>\n  );\n};\n\nexport default Button;',
181
  filePath: '/Users/dev/project/src/Button.jsx'
182
}
183
```
184

185
## Benefits of Error Enhancement
186

187
### For Developers
188
- **Cleaner Messages**: Removes redundant file path information
189
- **Source Context**: Complete source code for debugging
190
- **Precise Location**: Accurate line and column information
191
- **Better Navigation**: Absolute file paths for IDE integration
192

193
### For Tools and IDEs
194
- **Rich Context**: Full source code for syntax highlighting
195
- **Accurate Positioning**: Precise error location mapping
196
- **File Navigation**: Direct links to problematic files
197
- **Stack Trace Enhancement**: Better error reporting in development tools
198

199
### For Parcel Integration
200
- **Consistent Format**: Standardized error structure
201
- **Enhanced Diagnostics**: Better error reporting in build output
202
- **Source Map Support**: Compatible with source map error mapping
203
- **Development Experience**: Improved error messages in watch mode
204

205
**Usage Example:**
206

207
```javascript
208
// Internal error enhancement flow
209
try {
210
  // Babel transformation attempt
211
  const result = await babelCore.transformAsync(sourceCode, config);
212
} catch (originalError) {
213
  // Enhance error with source context
214
  const enhancedError = await babelErrorEnhancer(originalError, asset);
215
  
216
  // Enhanced error now contains:
217
  console.log(enhancedError.message);    // Clean error message
218
  console.log(enhancedError.loc);        // { line: 15, column: 8 }
219
  console.log(enhancedError.source);     // Complete source code
220
  console.log(enhancedError.filePath);   // Absolute file path
221
  
222
  // Throw enhanced error for Parcel to handle
223
  throw enhancedError;
224
}
225
```