Registry / web-framework / metro-bundler

metro-bundler

library0.22.1jsnpmunverified

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.

web-framework devops

npm install metro-bundler

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · METRO-BUNDLER

metro-bundler

web-frameworkjavascriptv0.22.1

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.

Metro

✓ import Metro from 'metro'

✗ const Metro = require('metro')

Metro's default export is the server instance. Use named imports for sub-parts.

Server

✓ import { Server } from 'metro'

✗ const { Server } = require('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

✓ import { loadConfig } from 'metro'

✗ const { loadConfig } = require('metro/config');

loadConfig is exported from 'metro' directly. Not from 'metro/config'.

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

metro --version

Debug

Known issues

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

affects: >=0.84.0

breakingv0.80.0 removed support for Babel 6; requires Babel 7+

fix

Upgrade your project's Babel to v7

affects: >=0.80.0

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`

affects: >=0.83.0

gotchaFast Refresh may not work in some proxied environments without keepalive

fix

Upgrade to v0.83.4+ or configure keepalive manually

affects: <0.83.4

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

fix

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

affects: >=0.72.0

gotchaUsing `require` for ES modules may cause runtime errors if not transpiled

fix

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

affects: >=0.80.0

Errors

Common errors & fixes

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

Missing or misconfigured React Native dependency

fix

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

SyntaxError: Unexpected token 'export'

Babel transform not applied to ES module syntax

fix

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

Error: Cannot find module 'metro-config'

Metro version mismatch or incorrect import path

fix

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

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

Port 8081 already in use

fix

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

Upgrade

Version history

0.22.1latest on npm

Audit

Dependencies

@react-native/community-cli-pluginoptionalRequired for Metro CLI integration with React Native

react-nativeoptionalMetro is designed to work with React Native applications

Agent activity

2 hits · last 30 days

node

Resources

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

packagehttps://www.npmjs.com/package/metro-bundler ↗

homepagehttps://metrobundler.dev ↗