Registry / metro-babel-transformer

metro-babel-transformer

library0.84.3jsnpmunverified

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.

npm install metro-babel-transformer

github ↗package ↗

INSTALL

IMPORT

SIG · METRO-BABEL-TRANSF

metro-babel-transformer

javascriptv0.84.3

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

getTransformOptions

✓ import { getTransformOptions } from 'metro-babel-transformer'

✗ const { getTransformOptions } = require('metro-babel-transformer')

Package ships TypeScript types; ES module syntax recommended. CommonJS require works but may not have type checking.

MetroBabelTransformer

✓ import MetroBabelTransformer from 'metro-babel-transformer'

✗ import * as 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.

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);

Debug

Known issues

breakingNode.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

affects: >=0.84.0

deprecatedThe function `getTransformOptions` is deprecated in favor of `customTransformOptions`.

fix

Use `customTransformOptions` instead of `getTransformOptions`.

affects: >=0.83.0

gotchaIf 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.

affects: <0.83.6

Errors

Common errors & fixes

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

Package not installed or incorrect import path.

fix

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

TypeError: MetroBabelTransformer is not a function

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

fix

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

Error: Cannot find module '@babel/core'

Missing peer dependency @babel/core.

fix

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

Upgrade

Version history

0.84.3latest on npm

Audit

Dependencies

@babel/coreoptionalProvides the Babel compiler used for transformation.

metrorequiredCore Metro package; required for transformer integration.

Agent activity

2 hits · last 30 days

node

Resources

githubhttps://github.com/facebook/metro ↗

packagehttps://www.npmjs.com/package/metro-babel-transformer ↗