Metro Babel Transformer

0.84.3 verified Sat Apr 25 auth: no javascript

The base Babel transformer for Metro, the JavaScript bundler for React Native. Current stable version is 0.84.3, with frequent releases (~monthly). This package provides the default Babel transformation pipeline used by Metro to transpile JavaScript/TypeScript files. It handles caching, config merging, and integration with Metro's build system. Key differentiators: it is the official transformer maintained by Meta, tightly coupled with Metro's caching and dependency resolution; supports custom Babel configs; and ships TypeScript types natively since v0.83.5. Alternatives like @react-native/babel-transformer exist but this is the core package.

Common errors

error Error: Cannot find module 'metro-babel-transformer' ↓

cause Package not installed or incorrect import path.

fix

Run npm install metro-babel-transformer --save-dev and ensure your code uses the correct import.

error TypeError: MetroBabelTransformer is not a function ↓

cause Using a default export incorrectly (e.g., namespace import).

fix

Use import MetroBabelTransformer from 'metro-babel-transformer' instead of import * as....

error Error: Cannot find module '@babel/core' ↓

cause Missing peer dependency @babel/core.

fix

Install @babel/core: npm install @babel/core --save-dev

Warnings

breaking Node.js versions earlier than 20.19.4 (including all v21, v23) are no longer supported in v0.84.0+. ↓

fix Upgrade Node.js to ^20.19.4 || ^22.13.0 || ^24.3.0 || >=25.0.0

deprecated The function `getTransformOptions` is deprecated in favor of `customTransformOptions`. ↓

fix Use `customTransformOptions` instead of `getTransformOptions`.

gotcha If you include a custom Babel config, make sure it is part of the transformer cache key to avoid stale caches. Metro includes it automatically since v0.83.6. ↓

fix Update to v0.83.6 or later, or manually add your Babel config path to the cache key.

Install

npm install metro-babel-transformer

yarn add metro-babel-transformer

pnpm add metro-babel-transformer

Imports

getTransformOptions
wrong
```
const { getTransformOptions } = require('metro-babel-transformer')
```
correct
```
import { getTransformOptions } from 'metro-babel-transformer'
```
Package ships TypeScript types; ES module syntax recommended. CommonJS require works but may not have type checking.

MetroBabelTransformer

wrong

import * as MetroBabelTransformer from 'metro-babel-transformer'

correct

import MetroBabelTransformer from 'metro-babel-transformer'

Default export is the transformer function; namespace import will cause runtime errors.

customTransformOptions
```
import { customTransformOptions } from 'metro-babel-transformer'
```
Available from v0.83.0; used to extend transform options.

Quickstart

Shows how to use the transformer function directly: instantiate with project root, then call with file contents.

// Example of using metro-babel-transformer programmatically
import MetroBabelTransformer from 'metro-babel-transformer';
import path from 'path';

const transformer = MetroBabelTransformer({
  // Required: root project directory
  projectRoot: process.cwd(),
  // Optional: custom Babel config path
  babelConfigPath: path.join(process.cwd(), 'babel.config.js'),
});

const result = transformer({
  filename: path.resolve('src/index.js'),
  sourceCode: 'const x = 1;',
  options: {
    dev: true,
    hot: false,
    platform: 'ios',
    minify: false,
    // Add custom transform options if needed
    customTransformOptions: {},
  },
});

console.log(result.code);
console.log('Map:', result.map);