Metro Bundler

0.22.1 verified Sat Apr 25 auth: no javascript

Metro is the JavaScript bundler for React Native, currently at v0.84.3. It is maintained by Meta and releases follow a regular cadence aligned with React Native releases. Metro focuses on sub-second reload cycles, fast startup, and handling thousands of modules. It is deeply integrated with React Native's development workflow, providing Fast Refresh, HMR, and a symmetric asset system. Compared to alternatives like Webpack, Metro is purpose-built for React Native, offering out-of-the-box support for React Native's module system, asset loading, and platform-specific code. It is configurable via metro.config.js and supports both CommonJS and ES modules.

Common errors

error Unable to resolve module `react-native` from `...` ↓

cause Missing or misconfigured React Native dependency

fix

Run npm install react-native and ensure metro.config.js has proper watchFolders

error SyntaxError: Unexpected token 'export' ↓

cause Babel transform not applied to ES module syntax

fix

Add @babel/preset-env or @babel/plugin-transform-modules-commonjs to Babel config

error Error: Cannot find module 'metro-config' ↓

cause Metro version mismatch or incorrect import path

fix

Use import { loadConfig } from 'metro' instead of 'metro-config'

error Metro server crashed: Error: listen EADDRINUSE :::8081 ↓

cause Port 8081 already in use

fix

Kill the process using port 8081 or set a different port in metro.config.js

Warnings

breaking v0.84.0 drops support for Node v21, v23, and LTS minors released before v20.19 ↓

fix Upgrade to Node v20.19 or later, or pin Metro to v0.83.x

breaking v0.80.0 removed support for Babel 6; requires Babel 7+ ↓

fix Upgrade your project's Babel to v7

deprecated `metro.config.js` is deprecated in favor of `metro.config.mjs` or `.metro/metro.config.js` ↓

fix Rename to `metro.config.mjs` or move to `.config/metro.js`

gotcha Fast Refresh may not work in some proxied environments without keepalive ↓

fix Upgrade to v0.83.4+ or configure keepalive manually

breaking Asset system changed: require('image.png') now returns an object instead of a number ↓

fix Update code to handle asset objects, e.g., asset.uri

gotcha Using `require` for ES modules may cause runtime errors if not transpiled ↓

fix Ensure Babel configuration includes @babel/plugin-transform-modules-commonjs

Install

npm install metro-bundler

yarn add metro-bundler

pnpm add metro-bundler

Imports

Metro
wrong
```
const Metro = require('metro')
```
correct
```
import Metro from 'metro'
```
Metro's default export is the server instance. Use named imports for sub-parts.
Server
wrong
```
const { Server } = require('metro')
```
correct
```
import { Server } from 'metro'
```
Named export from 'metro'. Use when creating a custom Metro server.
createConnectMiddleware
```
import { createConnectMiddleware } from 'metro'
```
Available since v0.80.0. Creates Connect middleware.
loadConfig
wrong
```
const { loadConfig } = require('metro/config');
```
correct
```
import { loadConfig } from 'metro'
```
loadConfig is exported from 'metro' directly. Not from 'metro/config'.

Quickstart

Starts a Metro bundler server with custom Express integration.

import Metro from 'metro';
import express from 'express';

const app = express();
const config = await Metro.loadConfig();
const metroServer = await Metro.runMetro(config);

app.use(metroServer.processRequest.bind(metroServer));
app.listen(8081, () => {
  console.log('Metro server running on 8081');
});