0
# Metro Transform Worker
1

2
Metro Transform Worker is the core transformation engine for Meta's Metro JavaScript bundler. It handles the conversion of JavaScript, TypeScript, JSX, JSON, and asset files through a comprehensive Babel-based pipeline, providing dependency analysis, code optimization, minification, and source map generation for React Native and web applications.
3

4
## Package Information
5

6
- **Package Name**: metro-transform-worker
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install metro-transform-worker`
10

11
## Core Imports
12

13
```javascript
14
const { transform, getCacheKey } = require("metro-transform-worker");
15
```
16

17
For ESM:
18

19
```javascript
20
import { transform, getCacheKey } from "metro-transform-worker";
21
```
22

23
## Basic Usage
24

25
```javascript
26
const { transform } = require("metro-transform-worker");
27
const fs = require("fs");
28

29
// Basic file transformation
30
const config = {
31
  babelTransformerPath: require.resolve("@react-native/metro-babel-transformer"),
32
  minifierPath: require.resolve("metro-minify-terser"),
33
  assetRegistryPath: "react-native/Libraries/Image/AssetRegistry",
34
  assetPlugins: [],
35
  // ... other configuration options
36
};
37

38
const options = {
39
  dev: true,
40
  hot: false,
41
  inlinePlatform: false,
42
  inlineRequires: false,
43
  minify: false,
44
  platform: "ios",
45
  type: "module",
46
  unstable_transformProfile: "default",
47
};
48

49
// Transform a JavaScript file
50
const fileData = fs.readFileSync("./src/MyComponent.js");
51
const result = await transform(
52
  config,
53
  "/path/to/project/root",
54
  "./src/MyComponent.js",
55
  fileData,
56
  options
57
);
58

59
console.log(result.output[0].data.code); // Transformed code
60
console.log(result.dependencies); // Module dependencies
61
```
62

63
## Architecture
64

65
Metro Transform Worker is built around several key components:
66

67
- **Transformation Pipeline**: Multi-stage processing including parsing, Babel transformation, dependency collection, and optimization
68
- **File Type Handlers**: Specialized processing for JavaScript, TypeScript, JSX, JSON, and asset files with optional Hermes bytecode output
69
- **Plugin System**: Extensible Babel plugin integration with Metro-specific transform plugins
70
- **Caching System**: Cache key generation for efficient incremental builds
71
- **Source Maps**: Comprehensive source map generation and handling throughout the pipeline
72
- **Error Handling**: Detailed error reporting with file context and debugging information
73

74
## Capabilities
75

76
### Core Transformation
77

78
Primary transformation function that processes files through the complete Metro pipeline, handling JavaScript/TypeScript/JSX transformations, dependency analysis, and code optimization.
79

80
```javascript { .api }
81
/**
82
 * Transform files through Metro's complete transformation pipeline
83
 * @param config - Transformer configuration object
84
 * @param projectRoot - Absolute path to project root directory
85
 * @param filename - Relative path to file being transformed
86
 * @param data - File content as Buffer
87
 * @param options - Transformation options
88
 * @returns Promise resolving to transformation result with dependencies and output
89
 */
90
function transform(
91
  config: JsTransformerConfig,
92
  projectRoot: string,
93
  filename: string,
94
  data: Buffer,
95
  options: JsTransformOptions
96
): Promise<TransformResponse>;
97

98
interface TransformResponse {
99
  dependencies: TransformResultDependency[];
100
  output: (JsOutput | BytecodeOutput)[];
101
}
102

103
interface JsOutput {
104
  data: {
105
    code: string;
106
    lineCount: number;
107
    map: MetroSourceMapSegmentTuple[];
108
    functionMap: FBSourceFunctionMap | null;
109
  };
110
  type: JSFileType;
111
}
112
```
113

114
[Core Transformation](./core-transformation.md)
115

116
### Cache Management
117

118
Cache key generation for efficient incremental builds and cache invalidation.
119

120
```javascript { .api }
121
/**
122
 * Generate cache key for transformer configuration
123
 * @param config - Transformer configuration object
124
 * @returns String cache key based on configuration and dependencies
125
 */
126
function getCacheKey(config: JsTransformerConfig): string;
127
```
128

129
[Cache Management](./cache-management.md)
130

131
### Configuration System
132

133
Comprehensive configuration system for customizing transformation behavior, Babel integration, and optimization settings.
134

135
```javascript { .api }
136
interface JsTransformerConfig {
137
  assetPlugins: ReadonlyArray<string>;
138
  assetRegistryPath: string;
139
  asyncRequireModulePath: string;
140
  babelTransformerPath: string;
141
  dynamicDepsInPackages: DynamicRequiresBehavior;
142
  enableBabelRCLookup: boolean;
143
  enableBabelRuntime: boolean | string;
144
  globalPrefix: string;
145
  hermesParser: boolean;
146
  minifierConfig: MinifierConfig;
147
  minifierPath: string;
148
  optimizationSizeLimit: number;
149
  publicPath: string;
150
  allowOptionalDependencies: AllowOptionalDependencies;
151
  unstable_collectDependenciesPath: string;
152
  unstable_dependencyMapReservedName?: string;
153
  unstable_disableModuleWrapping: boolean;
154
  unstable_disableNormalizePseudoGlobals: boolean;
155
  unstable_compactOutput: boolean;
156
  unstable_allowRequireContext: boolean;
157
  unstable_memoizeInlineRequires?: boolean;
158
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
159
  unstable_renameRequire?: boolean;
160
}
161

162
interface JsTransformOptions {
163
  customTransformOptions?: CustomTransformOptions;
164
  dev: boolean;
165
  experimentalImportSupport?: boolean;
166
  hot: boolean;
167
  inlinePlatform: boolean;
168
  inlineRequires: boolean;
169
  minify: boolean;
170
  nonInlinedRequires?: ReadonlyArray<string>;
171
  platform?: string;
172
  runtimeBytecodeVersion?: number;
173
  type: Type;
174
  unstable_disableES6Transforms?: boolean;
175
  unstable_memoizeInlineRequires?: boolean;
176
  unstable_nonMemoizedInlineRequires?: ReadonlyArray<string>;
177
  unstable_staticHermesOptimizedRequire?: boolean;
178
  unstable_transformProfile: TransformProfile;
179
}
180
```
181

182
[Configuration System](./configuration.md)
183

184
### Error Handling
185

186
Detailed error handling with context and debugging information for transformation failures.
187

188
```javascript { .api }
189
class InvalidRequireCallError extends Error {
190
  innerError: InternalInvalidRequireCallError;
191
  filename: string;
192
  
193
  constructor(innerError: InternalInvalidRequireCallError, filename: string);
194
}
195
```
196

197
[Error Handling](./error-handling.md)
198

199
## Types
200

201
### Core Types
202

203
```javascript { .api }
204
type Type = "script" | "module" | "asset";
205
type JSFileType = "js/script" | "js/module" | "js/module/asset";
206
type BytecodeFileType = "bytecode/module" | "bytecode/module/asset" | "bytecode/script";
207
type DynamicRequiresBehavior = "reject" | "throwAtRuntime";
208

209
interface MinifierOptions {
210
  code: string;
211
  map?: BasicSourceMap;
212
  filename: string;
213
  reserved: ReadonlyArray<string>;
214
  config: MinifierConfig;
215
}
216

217
interface MinifierResult {
218
  code: string;
219
  map?: BasicSourceMap;
220
}
221

222
type Minifier = (options: MinifierOptions) => MinifierResult | Promise<MinifierResult>;
223

224
type TransformProfile = "default" | "hermes-stable" | "hermes-canary";
225
```
226

227
### Metro Integration Types
228

229
```javascript { .api }
230
interface TransformResultDependency {
231
  name: string;
232
  type: string;
233
  // Additional Metro-specific dependency metadata
234
}
235

236
type MetroSourceMapSegmentTuple = [number, number, number?, number?, string?];
237

238
interface FBSourceFunctionMap {
239
  names: ReadonlyArray<string>;
240
  mappings: string;
241
}
242

243
interface BytecodeOutput {
244
  data: unknown;
245
  type: BytecodeFileType;
246
}
247
```