0
# Configuration System
1

2
Metro Transform Worker's comprehensive configuration system allows fine-tuned control over Babel transformations, asset processing, minification, and optimization behavior.
3

4
## Capabilities
5

6
### Transformer Configuration
7

8
Main configuration object that controls all aspects of the transformation pipeline.
9

10
```javascript { .api }
11
interface JsTransformerConfig {
12
  /** Array of asset plugin module paths for custom asset processing */
13
  assetPlugins: ReadonlyArray<string>;
14
  /** Path to asset registry module (typically React Native's AssetRegistry) */
15
  assetRegistryPath: string;
16
  /** Path to async require module for dynamic imports */
17
  asyncRequireModulePath: string;
18
  /** Absolute path to Babel transformer module */
19
  babelTransformerPath: string;
20
  /** Behavior for dynamic requires in node_modules packages */
21
  dynamicDepsInPackages: DynamicRequiresBehavior;
22
  /** Enable .babelrc file lookup during transformation */
23
  enableBabelRCLookup: boolean;
24
  /** Enable Babel runtime helpers (true/false or runtime module path) */
25
  enableBabelRuntime: boolean | string;
26
  /** Global prefix for Metro-generated variables */
27
  globalPrefix: string;
28
  /** Use Hermes parser instead of Babylon */
29
  hermesParser: boolean;
30
  /** Configuration object passed to minifier */
31
  minifierConfig: MinifierConfig;
32
  /** Absolute path to minifier module */
33
  minifierPath: string;
34
  /** File size limit for applying optimizations (bytes) */
35
  optimizationSizeLimit: number;
36
  /** Public path for serving assets */
37
  publicPath: string;
38
  /** How to handle optional dependencies */
39
  allowOptionalDependencies: AllowOptionalDependencies;
40
  /** Path to custom dependency collection module */
41
  unstable_collectDependenciesPath: string;
42
  /** Reserved name for dependency map variable */
43
  unstable_dependencyMapReservedName?: string;
44
  /** Disable CommonJS module wrapping */
45
  unstable_disableModuleWrapping: boolean;
46
  /** Disable pseudo-global normalization optimization */
47
  unstable_disableNormalizePseudoGlobals: boolean;
48
  /** Generate compact output without extra whitespace */
49
  unstable_compactOutput: boolean;
50
  /** Enable require.context support for dynamic imports */
51
  unstable_allowRequireContext: boolean;
52
  /** Enable memoization for inline requires */
53
  unstable_memoizeInlineRequires?: boolean;
54
  /** Module specifiers to exclude from inline require memoization */
55
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
56
  /** Rename scoped require functions to avoid conflicts */
57
  unstable_renameRequire?: boolean;
58
}
59
```
60

61
**Usage Examples:**
62

63
```javascript
64
// Basic React Native configuration
65
const config = {
66
  assetPlugins: [],
67
  assetRegistryPath: "react-native/Libraries/Image/AssetRegistry",
68
  asyncRequireModulePath: "metro-runtime/src/modules/asyncRequire",
69
  babelTransformerPath: require.resolve("@react-native/metro-babel-transformer"),
70
  dynamicDepsInPackages: "throwAtRuntime",
71
  enableBabelRCLookup: true,
72
  enableBabelRuntime: false,
73
  globalPrefix: "",
74
  hermesParser: false,
75
  minifierConfig: {
76
    output: {
77
      ascii_only: true,
78
      quote_style: 3,
79
      wrap_iife: true,
80
    },
81
    sourceMap: {
82
      includeSources: false,
83
    },
84
    toplevel: false,
85
    compress: {
86
      reduce_funcs: false,
87
    },
88
  },
89
  minifierPath: require.resolve("metro-minify-terser"),
90
  optimizationSizeLimit: 150000,
91
  publicPath: "/assets",
92
  allowOptionalDependencies: "ignore",
93
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
94
  unstable_disableModuleWrapping: false,
95
  unstable_compactOutput: false,
96
  unstable_allowRequireContext: false,
97
};
98

99
// Web development configuration
100
const webConfig = {
101
  ...config,
102
  assetRegistryPath: "metro-runtime/src/modules/assetRegistry",
103
  enableBabelRuntime: "@babel/runtime",
104
  publicPath: "/static/assets/",
105
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
106
  unstable_compactOutput: true,
107
  unstable_allowRequireContext: true,
108
};
109

110
// Development configuration with optimizations disabled
111
const devConfig = {
112
  ...config,
113
  enableBabelRCLookup: false,
114
  optimizationSizeLimit: 0, // Disable size-based optimizations
115
  unstable_collectDependenciesPath: "metro/private/ModuleGraph/worker/collectDependencies",
116
  unstable_disableNormalizePseudoGlobals: true,
117
};
118
```
119

120
### Transform Options
121

122
Per-transformation options that control behavior for individual files.
123

124
```javascript { .api }
125
interface JsTransformOptions {
126
  /** Custom transformation options passed to Babel transformer */
127
  customTransformOptions?: CustomTransformOptions;
128
  /** Development mode (affects optimizations and debugging features) */
129
  dev: boolean;
130
  /** Enable experimental ES6 import/export support */
131
  experimentalImportSupport?: boolean;
132
  /** Hot reloading support */
133
  hot: boolean;
134
  /** Inline platform-specific code branches */
135
  inlinePlatform: boolean;
136
  /** Inline require calls for performance */
137
  inlineRequires: boolean;
138
  /** Enable minification */
139
  minify: boolean;
140
  /** Module specifiers to exclude from inline requires */
141
  nonInlinedRequires?: ReadonlyArray<string>;
142
  /** Target platform (ios, android, web, etc.) */
143
  platform?: string;
144
  /** Runtime bytecode version for Hermes compilation */
145
  runtimeBytecodeVersion?: number;
146
  /** File type being transformed */
147
  type: Type;
148
  /** Disable ES6 to ES5 transformations */
149
  unstable_disableES6Transforms?: boolean;
150
  /** Enable memoization for inline requires */
151
  unstable_memoizeInlineRequires?: boolean;
152
  /** Module specifiers to exclude from memoization */
153
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
154
  /** Enable static Hermes-optimized require calls */
155
  unstable_staticHermesOptimizedRequire?: boolean;
156
  /** Transformation profile for target runtime */
157
  unstable_transformProfile: TransformProfile;
158
}
159
```
160

161
**Usage Examples:**
162

163
```javascript
164
// Development options
165
const devOptions = {
166
  dev: true,
167
  hot: true,
168
  inlinePlatform: false,
169
  inlineRequires: false,
170
  minify: false,
171
  platform: "ios",
172
  type: "module",
173
  unstable_transformProfile: "default",
174
};
175

176
// Production options with optimizations
177
const prodOptions = {
178
  dev: false,
179
  hot: false,
180
  inlinePlatform: true,
181
  inlineRequires: true,
182
  minify: true,
183
  nonInlinedRequires: ["react", "react-native"],
184
  platform: "ios",
185
  type: "module",
186
  unstable_transformProfile: "default",
187
};
188

189
// Hermes-optimized options
190
const hermesOptions = {
191
  ...prodOptions,
192
  runtimeBytecodeVersion: 74, // Hermes bytecode version
193
  unstable_staticHermesOptimizedRequire: true,
194
  unstable_transformProfile: "hermes-stable",
195
};
196

197
// Web bundle options
198
const webOptions = {
199
  dev: false,
200
  experimentalImportSupport: true,
201
  inlinePlatform: true,
202
  inlineRequires: true,
203
  minify: true,
204
  platform: "web",
205
  type: "module",
206
  unstable_disableES6Transforms: false,
207
  unstable_transformProfile: "default",
208
};
209
```
210

211
### Configuration Types
212

213
#### Dynamic Dependencies Behavior
214

215
```javascript { .api }
216
type DynamicRequiresBehavior = "reject" | "throwAtRuntime";
217
```
218

219
- **"reject"**: Reject dynamic requires at build time (strict mode)
220
- **"throwAtRuntime"**: Allow in node_modules but throw at runtime for app code
221

222
#### Transform Profiles
223

224
```javascript { .api }
225
type TransformProfile = "default" | "hermes-stable" | "hermes-canary";
226
```
227

228
- **"default"**: Standard JavaScript transformation for V8/JSC
229
- **"hermes-stable"**: Optimizations for stable Hermes engine
230
- **"hermes-canary"**: Optimizations for experimental Hermes features
231

232
#### File Types
233

234
```javascript { .api }
235
type Type = "script" | "module" | "asset";
236
```
237

238
- **"script"**: Standalone script (no module wrapping)
239
- **"module"**: CommonJS/ES6 module (standard bundling)
240
- **"asset"**: Static asset (images, fonts, etc.)
241

242
#### Optional Dependencies Handling
243

244
```javascript { .api }
245
type AllowOptionalDependencies = "ignore" | "reject";
246
```
247

248
- **"ignore"**: Skip missing optional dependencies
249
- **"reject"**: Fail build on missing optional dependencies
250

251
### Minifier Configuration
252

253
The minifier configuration is passed directly to the configured minifier (typically Terser):
254

255
```javascript { .api }
256
interface MinifierConfig {
257
  /** Output formatting options */
258
  output?: {
259
    /** Generate ASCII-only output */
260
    ascii_only?: boolean;
261
    /** Quote style for string literals */
262
    quote_style?: number;
263
    /** Wrap immediately invoked function expressions */
264
    wrap_iife?: boolean;
265
  };
266
  /** Source map generation options */
267
  sourceMap?: {
268
    /** Include original source code in source maps */
269
    includeSources?: boolean;
270
  };
271
  /** Enable top-level variable mangling */
272
  toplevel?: boolean;
273
  /** Compression/optimization options */
274
  compress?: {
275
    /** Reduce function expressions to function declarations */
276
    reduce_funcs?: boolean;
277
  };
278
}
279
```
280

281
### Custom Transform Options
282

283
Extended options for specific Babel transformers and Metro features:
284

285
```javascript { .api }
286
interface CustomTransformOptions {
287
  /** Enable static Hermes-optimized require calls */
288
  unstable_staticHermesOptimizedRequire?: boolean;
289
  /** Custom Babel transformer-specific options */
290
  [key: string]: any;
291
}
292
```
293

294
### Configuration Validation
295

296
Metro Transform Worker validates configuration at runtime and provides detailed error messages for invalid settings:
297

298
- **Path validation**: Ensures transformer and minifier paths are resolvable
299
- **Type checking**: Validates configuration object structure
300
- **Compatibility checks**: Warns about incompatible option combinations
301
- **Default handling**: Provides sensible defaults for optional configuration