0
# Configuration Management
1

2
Babel configuration loading, validation, and default configuration generation with automatic dependency detection and performance optimization warnings.
3

4
## Capabilities
5

6
### Configuration Loading
7

8
Main function for loading and processing Babel configuration from the filesystem or building intelligent defaults.
9

10
```javascript { .api }
11
/**
12
 * Loads Babel configuration for the current asset
13
 * Discovers filesystem configs or builds default configuration
14
 * @param config - Parcel configuration object
15
 * @param options - Plugin options
16
 * @param logger - Plugin logger for warnings and errors
17
 * @returns Promise resolving to BabelConfigResult or null if no transformation needed
18
 */
19
export async function load(
20
  config: Config,
21
  options: PluginOptions,
22
  logger: PluginLogger
23
): Promise<BabelConfigResult | null>;
24

25
interface BabelConfigResult {
26
  internal: boolean;           // True if using default config, false for filesystem config
27
  config: BabelConfig;         // The actual Babel configuration
28
  targets?: mixed;             // Babel targets for preset-env
29
  syntaxPlugins?: mixed;       // Additional syntax plugins to enable
30
}
31

32
interface BabelConfig {
33
  plugins?: Array<any>;        // Babel plugins array
34
  presets?: Array<any>;        // Babel presets array
35
}
36
```
37

38
**Configuration Discovery Process:**
39

40
1. **Skip Non-Source Files**: Returns null for files in node_modules
41
2. **File Invalidation Setup**: Watches for Babel config file creation
42
3. **Config Resolution**: Searches for existing Babel configuration files
43
4. **Fallback to Defaults**: Uses `buildDefaultBabelConfig` if no config found
44
5. **Babel Core Loading**: Loads and validates @babel/core dependency
45
6. **Environment Setup**: Configures BABEL_ENV and NODE_ENV handling
46
7. **Partial Config Loading**: Uses Babel's loadPartialConfigAsync
47
8. **Dependency Tracking**: Tracks config files for invalidation
48
9. **Performance Warnings**: Warns about non-optimal configurations
49
10. **Cache Key Generation**: Creates cache keys for configuration
50

51
### Default Configuration Builder
52

53
Builds intelligent default Babel configuration when no filesystem config is found.
54

55
```javascript { .api }
56
/**
57
 * Builds default Babel configuration for files without explicit config
58
 * Primarily handles Flow type stripping with JSX support
59
 * @param options - Plugin options
60
 * @param config - Parcel configuration object
61
 * @returns Promise resolving to BabelConfigResult or null if no config needed
62
 */
63
async function buildDefaultBabelConfig(
64
  options: PluginOptions,
65
  config: Config
66
): Promise<BabelConfigResult | null>;
67
```
68

69
**Default Configuration Logic:**
70

71
- **TypeScript Files**: Returns null (handled by TypeScript transformer)
72
- **Flow Detection**: Enables Flow type stripping if `flow-bin` dependency found
73
- **JSX Support**: Adds JSX syntax plugin when React-like dependencies detected
74
- **Minimal Configuration**: Only applies necessary transformations
75

76
**Usage Example:**
77

78
```javascript
79
// Internal usage - called when no filesystem config found
80
const defaultConfig = await buildDefaultBabelConfig(pluginOptions, parcelConfig);
81

82
// Typical default config for Flow + JSX file:
83
// {
84
//   internal: true,
85
//   config: {
86
//     plugins: [
87
//       ['@babel/plugin-transform-flow-strip-types', { requireDirective: true }]
88
//     ]
89
//   },
90
//   syntaxPlugins: ['jsx']
91
// }
92
```
93

94
### Supported Configuration Files
95

96
The configuration system recognizes all standard Babel configuration file formats:
97

98
```javascript { .api }
99
const BABEL_CONFIG_FILENAMES = [
100
  '.babelrc',
101
  '.babelrc.js',
102
  '.babelrc.json', 
103
  '.babelrc.cjs',
104
  '.babelrc.mjs',
105
  '.babelignore',
106
  'babel.config.js',
107
  'babel.config.json',
108
  'babel.config.mjs',
109
  'babel.config.cjs'
110
];
111
```
112

113
### Plugin Dependency Management
114

115
Tracks and manages Babel plugin and preset dependencies for proper invalidation.
116

117
```javascript { .api }
118
/**
119
 * Defines plugin dependencies for cache invalidation
120
 * @param config - Parcel configuration object
121
 * @param babelConfig - Babel configuration with plugins/presets
122
 * @param options - Plugin options
123
 */
124
function definePluginDependencies(
125
  config: Config,
126
  babelConfig: BabelConfig | null,
127
  options: PluginOptions
128
): void;
129
```
130

131
**Dependency Tracking Features:**
132
- Adds dev dependencies for all used plugins and presets
133
- Configures additional invalidations for @babel/core
134
- Ensures cache invalidation when plugins or dependencies update
135
- Handles relative path resolution from project root
136

137
### Configuration Validation
138

139
Detects problematic configurations and provides performance warnings.
140

141
```javascript { .api }
142
/**
143
 * Warns about redundant presets that may impact performance
144
 * @param fs - File system interface
145
 * @param babelConfig - Loaded Babel configuration
146
 * @param logger - Plugin logger for warnings
147
 */
148
async function warnOnRedundantPlugins(
149
  fs: FileSystem,
150
  babelConfig: PartialConfig,
151
  logger: PluginLogger
152
): Promise<void>;
153
```
154

155
**Redundant Presets Detection:**
156
- `@babel/preset-env` (conflicts with Parcel's builtin transpilation)
157
- `@babel/preset-react` (handled automatically)
158
- `@babel/preset-typescript` (conflicts with TypeScript transformer)
159
- `@parcel/babel-preset-env` (Parcel-specific alternative)
160

161
**Performance Warnings:**
162
- **JavaScript Config Files**: Warns about non-cacheable JS config files
163
- **Runtime Requires**: Warns about `require()` calls in configuration
164
- **Redundant Presets**: Suggests removing unnecessary presets
165
- **Target Incompatibility**: Warns about @babel/preset-env target conflicts
166

167
### Environment Configuration
168

169
Handles Babel environment variables and mode configuration.
170

171
```javascript { .api }
172
// Environment variables monitored for invalidation
173
config.invalidateOnEnvChange('BABEL_ENV');
174
config.invalidateOnEnvChange('NODE_ENV');
175

176
// Environment name resolution priority:
177
// 1. BABEL_ENV environment variable
178
// 2. NODE_ENV environment variable  
179
// 3. Parcel mode (if 'production' or 'development')
180
// 4. Default to 'development'
181
```
182

183
**Usage Examples:**
184

185
```javascript
186
// Typical configuration loading flow
187
const configResult = await load(parcelConfig, pluginOptions, logger);
188

189
if (configResult) {
190
  console.log('Config type:', configResult.internal ? 'default' : 'filesystem');
191
  console.log('Babel config:', configResult.config);
192
  console.log('Targets:', configResult.targets);
193
  console.log('Syntax plugins:', configResult.syntaxPlugins);
194
}
195

196
// Example filesystem config result:
197
// {
198
//   internal: false,
199
//   config: {
200
//     presets: [['@babel/preset-env', { targets: { node: '16' } }]],
201
//     plugins: ['@babel/plugin-proposal-class-properties']
202
//   },
203
//   targets: { node: '16.0.0' },
204
//   syntaxPlugins: ['jsx']
205
// }
206
```
207

208
## Configuration Caching
209

210
- **Static Configs**: JSON/RC files are cached based on content hash
211
- **Dynamic Configs**: JS config files invalidate on startup
212
- **Dependency Tracking**: Plugin/preset changes trigger re-compilation
213
- **Environment Sensitivity**: BABEL_ENV/NODE_ENV changes invalidate cache
214

215
## Error Handling
216

217
- **Missing Dependencies**: Automatic installation with shouldAutoInstall flag
218
- **Invalid Configurations**: Clear error messages with file context
219
- **Version Conflicts**: Warnings for incompatible @babel/core versions
220
- **File Permission Issues**: Graceful handling of unreadable config files