Metro Babel Register

Metro Babel Register provides internal Babel registration and configuration specifically designed for Metro monorepo development workflows. It offers a standardized way to configure Babel transformations for Metro's internal build system, including support for TypeScript, Flow, and modern JavaScript features. This is a private monorepo package used internally by Metro and is not published as a standalone npm package.

Package Information

• Package Name: metro-babel-register
• Package Type: Private monorepo package (not published to npm)
• Language: JavaScript with Flow type annotations (all source files use Flow static typing)
• Usage: Internal to Metro monorepo - accessed via require from Metro's source tree

Core Imports

const { register, config, buildRegExps, unstable_registerForMetroMonorepo } = require("metro-babel-register");

For individual imports:

const { register } = require("metro-babel-register");

Note: This package is internal to the Metro monorepo and must be required from within Metro's source tree.

Basic Usage

const { register } = require("metro-babel-register");

// Register Babel for specific directories
register(['/path/to/src', '/path/to/lib']);

// Register with early plugins
register(['/path/to/src'], {
  earlyPlugins: [
    ['@babel/plugin-proposal-optional-chaining']
  ]
});

Architecture

Metro Babel Register is built around several key components:

• Registration System: Core register() function that configures @babel/register with Metro-specific settings
• Configuration Generator: config() function that creates Babel configuration objects with Metro presets and plugins
• Path Utilities: buildRegExps() for creating file path matching patterns
• Monorepo Support: Special handling for Metro's own development workflow
• Multi-language Support: Built-in configurations for JavaScript, Flow, and TypeScript

Capabilities

Babel Registration

Register Babel with Metro-specific configuration for automatic code compilation.

/**
 * Registers Babel with Metro-specific configuration for compilation
 * @param onlyList - Array of RegExp or string patterns for files to transform
 * @param opts - Optional configuration object
 */
function register(
  onlyList: Array<RegExp | string>,
  opts?: {
    earlyPlugins?: Array<any>;
  }
): void;

Configuration Generation

Generate Babel configuration objects with Metro-specific plugins and presets.

/**
 * Returns Babel configuration object for Metro projects
 * @param onlyList - Array of RegExp or string patterns for files to transform
 * @param options - Optional configuration options
 * @returns Babel configuration object
 */
function config(
  onlyList: Array<RegExp | string>,
  options?: {
    lazy?: boolean;
    earlyPlugins?: Array<any>;
  }
): BabelCoreOptions;

interface BabelCoreOptions {
  babelrc: boolean;
  compact: boolean;
  configFile: boolean;
  browserslistConfigFile: boolean;
  ignore: Array<RegExp>;
  only: Array<RegExp | string>;
  plugins: Array<any>;
  presets: Array<any>;
  retainLines: boolean;
  sourceMaps: string;
  overrides: Array<{
    test: RegExp;
    plugins?: Array<any>;
    presets?: Array<any>;
  }>;
}

Path Pattern Utilities

Build regular expressions for file path matching with absolute paths.

/**
 * Builds regular expressions for path matching with absolute paths
 * @param basePath - Base directory path
 * @param dirPaths - Array of directory paths or RegExp patterns
 * @returns Array of compiled RegExp patterns
 */
function buildRegExps(
  basePath: string,
  dirPaths: Array<RegExp | string>
): Array<RegExp>;

Metro Monorepo Registration

Internal registration function for Metro's own development workflow.

/**
 * Registers Babel specifically for Metro monorepo development
 * This is an unstable API for internal Metro development use
 */
function unstable_registerForMetroMonorepo(): void;

Configuration Details

Supported File Extensions

The configuration automatically handles these file extensions (in processing order):

• .ts - TypeScript files
• .tsx - TypeScript JSX files
• .es6 - ES6 modules
• .es - ES modules
• .jsx - React JSX files
• .js - JavaScript files
• .mjs - ES modules

Note: Extensions are added to Babel's register configuration in addition to Babel's default extensions.

Built-in Plugins and Presets

Core Plugins:

• @babel/plugin-proposal-export-namespace-from - Export namespace syntax
• @babel/plugin-transform-modules-commonjs - CommonJS module transformation

Flow Support (for .js files):

• babel-plugin-syntax-hermes-parser - Hermes parser syntax support
• babel-plugin-transform-flow-enums - Flow enum transformations
• @babel/plugin-transform-flow-strip-types - Flow type stripping

TypeScript Support (for .ts/.tsx files):

• @babel/preset-typescript - TypeScript compilation
• babel-plugin-replace-ts-export-assignment - Export assignment handling
• babel-plugin-metro-replace-ts-require-assignment - Custom Metro TypeScript plugin

Custom Babel Plugin

Metro Babel Register includes a custom Babel plugin for TypeScript compatibility:

/**
 * Custom Babel plugin that transforms TypeScript import assignments
 * Converts `import thing = require('thing')` to `import thing from 'thing'`
 * @param options - Object containing template helper function
 * @param options.template - Babel template helper for creating AST nodes
 * @returns Babel plugin object
 */
function babelPluginMetroReplaceTsRequireAssignment({ template }): {
  name: 'metro-replace-ts-require-assignment';
  visitor: {
    TSImportEqualsDeclaration(path: any): void;
  };
};

Error Handling

The package includes several safety mechanisms:

• Double Registration Prevention: Prevents multiple registrations via isRegisteredForMetroMonorepo flag
• Environment Checks: Skips registration in production environments (NODE_ENV=production)
• Path Validation: Validates Metro source tree location before registration
• Release State Detection: Handles prepare-release script scenarios
• Meta Internal Support: Special handling for Meta's internal monorepo via FBSOURCE_ENV=1

Usage Examples

Basic Directory Registration

const { register } = require("metro-babel-register");

// Register for source and lib directories
register([
  './src',
  './lib',
  /packages\/.*\/src/
]);

Advanced Configuration

const { register, config } = require("metro-babel-register");

// Get configuration without registering
const babelConfig = config(['./src'], {
  lazy: true,
  earlyPlugins: [
    ['@babel/plugin-proposal-decorators', { legacy: true }]
  ]
});

// Use custom configuration
require('@babel/register')(babelConfig);

Path Pattern Building

const { buildRegExps } = require("metro-babel-register");

// Build absolute path patterns
const patterns = buildRegExps('/home/user/project', [
  'src',
  'lib',
  /packages\/.*\/src/
]);

console.log(patterns);
// [/^\/home\/user\/project\/src/, /^\/home\/user\/project\/lib/, /^\/home\/user\/project\/packages\/.*\/src/]

Metro Development Setup

const { unstable_registerForMetroMonorepo } = require("metro-babel-register");

// For Metro development (internal use)
unstable_registerForMetroMonorepo();