0
# @react-native/babel-preset
1

2
@react-native/babel-preset is a comprehensive Babel preset specifically designed for React Native applications. It provides all necessary plugins and configurations to transform JavaScript and TypeScript code for React Native development, including JSX transformation, Flow and TypeScript stripping, modern JavaScript syntax transformation, and platform-specific optimizations.
3

4
## Package Information
5

6
- **Package Name**: @react-native/babel-preset
7
- **Package Type**: npm
8
- **Language**: JavaScript
9
- **Installation**: `npm install @react-native/babel-preset --save-dev`
10

11
## Core Imports
12

13
```javascript
14
const preset = require("@react-native/babel-preset");
15
```
16

17
For direct access to specific functions:
18

19
```javascript
20
const { getPreset, passthroughSyntaxPlugins } = require("@react-native/babel-preset");
21
```
22

23
## Basic Usage
24

25
### Default Preset Configuration
26

27
```javascript
28
// babel.config.js
29
module.exports = {
30
  presets: ["@react-native/babel-preset"]
31
};
32
```
33

34
### With Options
35

36
```javascript
37
// babel.config.js
38
module.exports = {
39
  presets: [
40
    [
41
      "@react-native/babel-preset",
42
      {
43
        unstable_transformProfile: "hermes-stable",
44
        enableBabelRuntime: false,
45
        dev: true
46
      }
47
    ]
48
  ]
49
};
50
```
51

52
### Programmatic Usage
53

54
```javascript
55
const preset = require("@react-native/babel-preset");
56
const { getPreset } = require("@react-native/babel-preset");
57

58
// Using the main preset function
59
const config = preset(null, { dev: true });
60

61
// Using getPreset directly  
62
const directConfig = getPreset("const x = 1;", {
63
  unstable_transformProfile: "hermes-canary"
64
});
65
```
66

67
## Capabilities
68

69
### Main Preset Function
70

71
The primary export that returns Babel configuration based on environment and options.
72

73
```javascript { .api }
74
/**
75
 * Main preset function that returns Babel configuration
76
 * @param babel - Babel instance (usually null when used as preset)
77
 * @param options - Configuration options object
78
 * @returns Babel configuration object
79
 */
80
function preset(babel, options): BabelConfig;
81
```
82

83
### getPreset Function
84

85
Direct access to the preset generation logic with source code analysis.
86

87
```javascript { .api }
88
/**
89
 * Generates preset configuration with source code analysis
90
 * @param src - Source code string to analyze (null for generic config)
91
 * @param options - Configuration options object
92
 * @returns Babel configuration object
93
 */
94
function getPreset(src, options): BabelConfig;
95
```
96

97
### Passthrough Syntax Plugins
98

99
Array of syntax plugins for enabling experimental features without transformation.
100

101
```javascript { .api }
102
/**
103
 * Array of syntax plugins for experimental features
104
 * Enables parsing of nullish coalescing and optional chaining
105
 */
106
const passthroughSyntaxPlugins: BabelPlugin[];
107
```
108

109
### HMR Configuration
110

111
Hot Module Replacement configuration for development.
112

113
```javascript { .api }
114
/**
115
 * Returns Babel configuration for Hot Module Replacement
116
 * @returns Babel config with react-refresh plugin
117
 */
118
function hmrConfig(): BabelConfig;
119
```
120

121
## Configuration Options
122

123
### Transform Profile Options
124

125
Controls the target JavaScript engine and transformation level.
126

127
```javascript { .api }
128
interface TransformProfileOptions {
129
  /** Transform profile: 'default', 'hermes-stable', or 'hermes-canary' */
130
  unstable_transformProfile?: "default" | "hermes-stable" | "hermes-canary";
131
}
132
```
133

134
### Feature Toggle Options
135

136
Controls which transformations and features are enabled.
137

138
```javascript { .api }
139
interface FeatureOptions {
140
  /** Enable experimental JSX transform */
141
  useTransformReactJSXExperimental?: boolean;
142
  
143
  /** Disable static view configs codegen plugin */
144
  disableStaticViewConfigsCodegen?: boolean;
145
  
146
  /** Disable import/export to CommonJS transformation */
147
  disableImportExportTransform?: boolean;
148
  
149
  /** Enable lazy import transformation (boolean or function) */
150
  lazyImportExportTransform?: boolean | ((importSpecifier: string) => boolean);
151
  
152
  /** Enable development mode features */
153
  dev?: boolean;
154
  
155
  /** Disable deep import warnings in development */
156
  disableDeepImportWarnings?: boolean;
157
  
158
  /** Enable Babel runtime transformation */
159
  enableBabelRuntime?: boolean | string;
160
  
161
  /** Enable development tools */
162
  withDevTools?: boolean;
163
  
164
  /** Enable compact output */
165
  compact?: boolean;
166
}
167
```
168

169
### Hermes Parser Options
170

171
Configuration for the Hermes parser plugin.
172

173
```javascript { .api }
174
interface HermesParserOptions {
175
  /** Language types to parse */
176
  parseLangTypes?: string;
177
  
178
  /** React runtime target version */
179
  reactRuntimeTarget?: string;
180
  
181
  /** Additional Hermes parser options */
182
  hermesParserOptions?: Record<string, any>;
183
}
184
```
185

186
### Complete Options Interface
187

188
```javascript { .api }
189
interface PresetOptions extends TransformProfileOptions, FeatureOptions, HermesParserOptions {
190
  /** Enable experimental JSX transform */
191
  useTransformReactJSXExperimental?: boolean;
192
  
193
  /** Disable static view configs codegen plugin */
194
  disableStaticViewConfigsCodegen?: boolean;
195
  
196
  /** Disable import/export to CommonJS transformation */
197
  disableImportExportTransform?: boolean;
198
  
199
  /** Enable lazy import transformation */
200
  lazyImportExportTransform?: boolean | ((importSpecifier: string) => boolean);
201
  
202
  /** Enable development mode features */
203
  dev?: boolean;
204
  
205
  /** Disable deep import warnings in development */
206
  disableDeepImportWarnings?: boolean;
207
  
208
  /** Enable Babel runtime transformation */
209
  enableBabelRuntime?: boolean | string;
210
  
211
  /** Enable development tools */
212
  withDevTools?: boolean;
213
  
214
  /** Enable compact output */
215
  compact?: boolean;
216
  
217
  /** Transform profile for different JS engines */
218
  unstable_transformProfile?: "default" | "hermes-stable" | "hermes-canary";
219
  
220
  /** Hermes parser configuration */
221
  hermesParserOptions?: Record<string, any>;
222
}
223
```
224

225
## Core Types
226

227
```javascript { .api }
228
/** Babel configuration object returned by the preset */
229
interface BabelConfig {
230
  /** Preserve comments in output */
231
  comments: boolean;
232
  
233
  /** Enable compact output */
234
  compact: boolean;
235
  
236
  /** Configuration overrides for different file types and conditions */
237
  overrides: BabelOverride[];
238
}
239

240
/** Babel configuration override for specific conditions */
241
interface BabelOverride {
242
  /** Test function or pattern to match files */
243
  test?: (filename: string) => boolean;
244
  
245
  /** Babel plugins to apply */
246
  plugins: BabelPlugin[];
247
}
248

249
/** Babel plugin configuration */
250
type BabelPlugin = string | [string, any] | Function | [Function, any];
251
```
252

253
## Built-in Transformation Plugins
254

255
The preset includes numerous Babel plugins for comprehensive code transformation:
256

257
### Core JavaScript Transformations
258

259
- **@babel/plugin-transform-react-jsx**: JSX syntax transformation
260
- **@babel/plugin-transform-modules-commonjs**: ES modules to CommonJS
261
- **@babel/plugin-transform-classes**: ES6 classes transformation
262
- **@babel/plugin-transform-arrow-functions**: Arrow function transformation
263
- **@babel/plugin-transform-async-to-generator**: Async/await transformation
264
- **@babel/plugin-transform-destructuring**: Destructuring assignment transformation
265

266
### Modern JavaScript Features
267

268
- **@babel/plugin-transform-optional-chaining**: Optional chaining (`?.`) support
269
- **@babel/plugin-transform-nullish-coalescing-operator**: Nullish coalescing (`??`) support
270
- **@babel/plugin-transform-logical-assignment-operators**: Logical assignment operators
271
- **@babel/plugin-transform-numeric-separator**: Numeric separator support
272
- **@babel/plugin-transform-optional-catch-binding**: Optional catch binding
273

274
### React Native Specific Transformations
275

276
- **@react-native/babel-plugin-codegen**: Static view config code generation
277
- **babel-plugin-syntax-hermes-parser**: Hermes parser syntax support
278
- **babel-plugin-transform-flow-enums**: Flow enum transformation
279
- **@babel/plugin-transform-react-jsx-source**: JSX source location (dev)
280
- **@babel/plugin-transform-react-jsx-self**: JSX self prop (dev)
281

282
### Type System Support
283

284
- **@babel/plugin-transform-flow-strip-types**: Flow type annotation removal
285
- **@babel/plugin-transform-typescript**: TypeScript transformation
286
- **@babel/plugin-transform-class-properties**: Class property transformation
287
- **@babel/plugin-transform-private-methods**: Private method transformation
288

289
## Platform-Specific Behavior
290

291
### Hermes Engine Optimization
292

293
The preset provides specialized configurations for React Native's Hermes JavaScript engine:
294

295
- **hermes-stable**: Optimized for stable Hermes features
296
- **hermes-canary**: Includes experimental Hermes features with additional polyfills
297
- **default**: Standard configuration for other JavaScript engines
298

299
### Development vs Production
300

301
Automatically detects environment and applies appropriate transformations:
302

303
- **Development**: Includes HMR support, JSX source mapping, deep import warnings
304
- **Production**: Optimized output with minimal runtime overhead
305

306
## Error Handling
307

308
The preset handles various transformation edge cases:
309

310
- **TypeScript Detection**: Automatically applies TypeScript transformations for `.ts` and `.tsx` files
311
- **Flow Type Handling**: Strips Flow types while preserving enums
312
- **Import Path Warnings**: Warns about deprecated deep React Native imports in development
313
- **Engine Compatibility**: Adjusts transformations based on target JavaScript engine capabilities
314

315
## Usage Examples
316

317
### Custom Babel Configuration
318

319
```javascript
320
// babel.config.js
321
module.exports = {
322
  presets: [
323
    [
324
      "@react-native/babel-preset",
325
      {
326
        unstable_transformProfile: "hermes-stable",
327
        disableImportExportTransform: false,
328
        lazyImportExportTransform: (importSpecifier) => {
329
          // Custom lazy import logic
330
          return importSpecifier.includes("react-native");
331
        },
332
        dev: process.env.NODE_ENV === "development"
333
      }
334
    ]
335
  ],
336
  plugins: [
337
    // Additional plugins can be added here
338
  ]
339
};
340
```
341

342
### Metro Configuration Integration
343

344
```javascript
345
// metro.config.js
346
const { getDefaultConfig } = require("metro-config");
347

348
module.exports = (async () => {
349
  const config = await getDefaultConfig(__dirname);
350
  
351
  config.transformer.babelTransformerPath = require.resolve("metro-react-native-babel-transformer");
352
  
353
  return config;
354
})();
355
```
356

357
### Programmatic Configuration
358

359
```javascript
360
const { getPreset } = require("@react-native/babel-preset");
361

362
// Generate configuration for specific source code
363
const sourceCode = `
364
  import React from 'react';
365
  const Component = () => <div>Hello</div>;
366
`;
367

368
const config = getPreset(sourceCode, {
369
  dev: true,
370
  unstable_transformProfile: "hermes-canary"
371
});
372

373
console.log(config.plugins.length); // Number of plugins applied
374
```