metro-react-native-babel-transformer

0.77.0 verified Sat Apr 25 auth: no javascript

Babel transformer for React Native applications, part of the Metro bundler ecosystem. Current stable version is 0.84.3 (released 2025-04). Release cadence is frequent patches and minor versions. Key differentiator: it is the default transformer in React Native projects, handling JSX, Flow, and React Native-specific transforms. It integrates with Metro's caching and module system. Alternatives like @babel/preset-react are lower-level and do not include React Native's custom plugin set.

Common errors

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

cause Package is not installed or not in node_modules.

fix

Run 'npm install metro-react-native-babel-transformer' or add it to package.json.

error TypeError: transform is not a function ↓

cause Incorrect import: using ESM import statement instead of CJS require.

fix

Use 'const { transform } = require('metro-react-native-babel-transformer');'

error TypeError: src must be a Buffer ↓

cause Passing a string as src instead of Buffer.

fix

Pass Buffer.from(yourCodeString) as src.

error Error: The 'platform' option must be specified. ↓

cause Missing required option in transform call.

fix

Ensure options contains platform: 'ios' or 'android'.

Warnings

breaking Node v21, v23, and LTS minors before v20.19 are no longer supported. ↓

fix Upgrade to Node >=20.19 or >=22.x. Use version 0.83.x if stuck on older Node.

deprecated The package is part of Metro; consider using @react-native/babel-preset for direct Babel preset usage. ↓

fix Switch to @react-native/babel-preset for custom Babel configurations.

gotcha The transformer expects a Buffer for src, not a string. Passing a string may cause unexpected errors. ↓

fix Always call Buffer.from(code) before passing to transform.

gotcha The options object must include all required fields (dev, hot, platform, projectRoot, publicPath, minify). Missing fields can cause silent failures. ↓

fix Ensure options contains at least dev, hot, platform, projectRoot, publicPath, minify.

Install

npm install metro-react-native-babel-transformer

yarn add metro-react-native-babel-transformer

pnpm add metro-react-native-babel-transformer

Imports

metroReactNativeBabelTransformer

wrong

import metroReactNativeBabelTransformer from 'metro-react-native-babel-transformer';

correct

const metroReactNativeBabelTransformer = require('metro-react-native-babel-transformer');

This package is CJS-only; no ESM export. Default export is a function.

transform

wrong

import { transform } from 'metro-react-native-babel-transformer';

correct

const { transform } = require('metro-react-native-babel-transformer');

CommonJS destructuring works; ESM named import will fail.

getCacheKey

wrong

import getCacheKey from 'metro-react-native-babel-transformer';

correct

const { getCacheKey } = require('metro-react-native-babel-transformer');

getCacheKey is a named export, not default.

Quickstart

Demonstrates importing the transformer and running a basic transformation with typical options.

const babelTransformer = require('metro-react-native-babel-transformer');
const { transform, getCacheKey } = require('metro-react-native-babel-transformer');

// Example: transform a simple JSX file
const code = `import React from 'react'; const App = () => <View />;`;
const result = transform({
  filename: 'App.js',
  src: Buffer.from(code),
  options: {
    dev: true,
    hot: true,
    platform: 'ios',
    projectRoot: '/path/to/project',
    publicPath: '/assets',
    minify: false,
  },
});
console.log(result.code); // Transformed code string
console.log(result.map); // Source map object

// Cache key
console.log(getCacheKey());