metro-babel-register

0.84.3 verified Sat Apr 25 auth: no javascript

A babel/register configuration specifically for Metro, the JavaScript bundler for React Native. Version 0.84.3 is the latest stable release, with monthly releases on the Metro 0.84.x branch. It provides a pre-configured Babel require hook that enables on-the-fly transpilation of Node.js modules during Metro's build process. Key differentiators: it is deeply integrated with Metro's own Babel presets and plugins, ensuring compatibility with React Native's transform pipeline. Unlike generic `@babel/register`, this package automatically applies Metro's custom transforms and ignores, matching the bundler's internal behavior. It is designed for development-time use, typically in custom Metro plugins or scripts that need to evaluate source files with Babel. No external dependencies beyond @babel/register and @babel/core.

Common errors

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

cause Missing peer dependency @babel/core.

fix

npm install --save-dev @babel/core

error require() of ES Module /path/to/file.mjs not supported ↓

cause metro-babel-register does not handle native ESM files (.mjs). It only transpiles CommonJS modules.

fix

Use dynamic import() for .mjs files or convert to .js with CommonJS syntax.

error TypeError: metro_babel_register is not a function ↓

cause Using ESM import syntax (import ... from) which returns a module namespace object, not the function directly.

fix

Use require('metro-babel-register') instead of import, or use require('metro-babel-register').default() to get the function.

Warnings

breaking Node.js version requirements changed: v0.84.0 dropped support for Node v21, v23, and LTS minors before v20.19. ↓

fix Use Node >=20.19.4 (LTS) or >=22.x. Avoid Node v21, v23.

gotcha metro-babel-register modifies Node's require hook globally. This can interfere with other tools that rely on their own require hooks (e.g., ts-node or @babel/register). ↓

fix Only use in isolated scripts or ensure it is loaded after other hooks. Consider using it as the first require in your entry point.

gotcha The default ignore list excludes node_modules. If you need to transpile dependencies (e.g., for ES module interop), you must override the 'ignore' option. ↓

fix Provide an explicit `ignore` array that does not exclude the specific dependency, or set `ignore: []` to transpile everything.

deprecated Using default export without options may be deprecated in future versions; prefer calling with explicit config object. ↓

fix Call `require('metro-babel-register')({ /* options */ })` even if empty object.

Install

npm install metro-babel-register

yarn add metro-babel-register

pnpm add metro-babel-register

Imports

metro-babel-register
wrong
```
import 'metro-babel-register'
```
correct
```
require('metro-babel-register')
```
This package is intended for CommonJS require hook; ESM import may not work because it modifies Node's require.extensions before module evaluation. Use require() at the top of entry file.
register
wrong
```
import { register } from 'metro-babel-register'
```
correct
```
require('metro-babel-register').register()
```
The module exports a function `register` that can be called to customize the hook. ESM import is not recommended; use require for side-effect hook.

default

wrong

import metroBabelRegister from 'metro-babel-register'

correct

const metroBabelRegister = require('metro-babel-register'); metroBabelRegister();

The default export is a function that configures and applies the hook. Use require() to avoid ESM/CommonJS interop issues.

Quickstart

Shows how to require and configure metro-babel-register to enable on-the-fly transpilation for Node.js scripts, with example of overriding default Babel presets.

// Install: npm install --save-dev metro-babel-register

// In your entry script (e.g., metro-plugin.js):
require('metro-babel-register')({
  // Optional: override babel config options
  ignore: [/node_modules/], // default ignores node_modules
  presets: ['@babel/preset-env'],
  plugins: ['@babel/plugin-transform-modules-commonjs']
});

// Now you can require files that use modern JS/JSX:
const myModule = require('./path/to/component.jsx');

// Or simply use default behavior (no options):
require('metro-babel-register');
const { App } = require('./App');