0
# Metro Transform Plugins
1

2
Metro Transform Plugins is a collection of Babel transform plugins specifically designed for Metro, the JavaScript bundler for React Native. It provides essential code transformation utilities including constant folding, import/export handling, require inlining, and platform-specific optimizations that improve bundle performance and enable React Native features.
3

4
## Package Information
5

6
- **Package Name**: metro-transform-plugins
7
- **Package Type**: npm
8
- **Language**: JavaScript (with Flow types)
9
- **Installation**: `npm install metro-transform-plugins`
10
- **Node Version**: >= 20.19.4
11

12
## Core Imports
13

14
```javascript
15
const {
16
  addParamsToDefineCall,
17
  constantFoldingPlugin,
18
  importExportPlugin,
19
  inlinePlugin,
20
  inlineRequiresPlugin,
21
  normalizePseudoglobals,
22
  getTransformPluginCacheKeyFiles
23
} = require("metro-transform-plugins");
24
```
25

26
For ES modules (when available):
27

28
```javascript
29
import {
30
  addParamsToDefineCall,
31
  constantFoldingPlugin,
32
  importExportPlugin,
33
  inlinePlugin,
34
  inlineRequiresPlugin,
35
  normalizePseudoglobals,
36
  getTransformPluginCacheKeyFiles
37
} from "metro-transform-plugins";
38
```
39

40
## Basic Usage
41

42
```javascript
43
const babel = require("@babel/core");
44
const { constantFoldingPlugin, inlineRequiresPlugin } = require("metro-transform-plugins");
45

46
// Apply constant folding to optimize code
47
const result = babel.transformSync(sourceCode, {
48
  plugins: [
49
    constantFoldingPlugin({ types: babel.types, traverse: babel.traverse }),
50
    inlineRequiresPlugin
51
  ]
52
});
53

54
// Add parameters to a Metro define call
55
const { addParamsToDefineCall } = require("metro-transform-plugins");
56
const enhancedCode = addParamsToDefineCall(
57
  "define(['dep1', 'dep2'], function(a, b) { return a + b; })",
58
  { meta: true },
59
  ["extra", "data"]
60
);
61
```
62

63
## Architecture
64

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

67
- **Babel Plugin Architecture**: All main transformations are implemented as Babel plugins that integrate into Metro's bundling pipeline
68
- **Lazy Loading**: Exports use getter functions to load plugins on-demand for better startup performance  
69
- **Platform Optimizations**: Platform-specific transformations for React Native's multi-platform support
70
- **Performance Focus**: Code optimizations including constant folding, dead code elimination, and require inlining
71
- **Metro Integration**: Designed specifically for Metro bundler with cache key generation and bundle optimization features
72

73
## Capabilities
74

75
### Code Optimization
76

77
Core code optimization functionality including constant folding, dead code elimination, and expression evaluation at compile time.
78

79
```javascript { .api }
80
function constantFoldingPlugin(context: {
81
  types: Types,
82
  traverse: Traverse
83
}): PluginObj<State>;
84
```
85

86
[Code Optimization](./code-optimization.md)
87

88
### Module System Transformation
89

90
Transforms ES6 import/export statements into CommonJS require/exports for Metro's module system.
91

92
```javascript { .api }
93
function importExportPlugin(context: {
94
  types: Types
95
}): PluginObj<State>;
96

97
interface ImportExportPluginOptions {
98
  importDefault: string;
99
  importAll: string;  
100
  resolve: boolean;
101
  out?: { isESModule: boolean };
102
}
103
```
104

105
[Module System](./module-system.md)
106

107
### Platform-Specific Inlining
108

109
Inlines platform-specific checks, development flags, and environment variables for React Native optimization.
110

111
```javascript { .api }
112
function inlinePlugin(
113
  context: { types: Types },
114
  options: InlinePluginOptions
115
): PluginObj<State>;
116

117
interface InlinePluginOptions {
118
  dev: boolean;
119
  inlinePlatform: boolean;
120
  isWrapped: boolean;
121
  requireName?: string;
122
  platform: string;
123
}
124
```
125

126
[Platform Inlining](./platform-inlining.md)
127

128
### Require Optimization
129

130
Inlines top-level require() calls to enable lazy loading and reduce bundle overhead.
131

132
```javascript { .api }
133
function inlineRequiresPlugin(): PluginObj<State>;
134

135
interface InlineRequiresPluginOptions {
136
  ignoredRequires?: ReadonlyArray<string>;
137
  inlineableCalls?: ReadonlyArray<string>;
138
  nonMemoizedModules?: ReadonlyArray<string>;
139
  memoizeCalls?: boolean;
140
}
141
```
142

143
[Require Optimization](./require-optimization.md)
144

145
### Code Generation Utilities
146

147
Utility functions for Metro code generation and pseudoglobal variable management.
148

149
```javascript { .api }
150
function addParamsToDefineCall(
151
  code: string,
152
  ...paramsToAdd: Array<mixed>
153
): string;
154

155
function normalizePseudoglobals(
156
  ast: BabelNode,
157
  options?: NormalizePseudoGlobalsOptions
158
): ReadonlyArray<string>;
159

160
interface NormalizePseudoGlobalsOptions {
161
  reservedNames: ReadonlyArray<string>;
162
}
163

164
function getTransformPluginCacheKeyFiles(): ReadonlyArray<string>;
165
```
166

167
[Code Generation](./code-generation.md)
168

169
## Private API Access
170

171
Metro Transform Plugins also exposes individual modules through private exports for advanced usage:
172

173
```javascript
174
// Access individual plugin files
175
const inlineRequires = require("metro-transform-plugins/private/inline-requires-plugin");
176
const constantFolding = require("metro-transform-plugins/private/constant-folding-plugin");
177
```
178

179
Note: Private APIs may change between versions and should be used with caution.
180

181
## Common Types
182

183
```javascript { .api }
184
// Babel plugin object interface
185
interface PluginObj<State = {}> {
186
  name?: string;
187
  visitor: Visitor<State>;
188
}
189

190
// Common state interface used by plugins
191
interface State {
192
  opts?: PluginOptions;
193
  // Plugin-specific state properties
194
}
195

196
// Babel AST node types
197
type BabelNode = any; // Represents any Babel AST node
198
type BabelNodeExpression = any; // Babel expression node
199
type BabelNodeStatement = any; // Babel statement node
200
type BabelNodeProgram = any; // Babel program node
201
```