{"id":18553,"library":"metro-pnpm","title":"Metro Bundler","description":"Metro is the default JavaScript bundler for React Native, optimized for sub-second reload cycles and fast startup. Current stable version is 0.84.3 (released 2025-03-01), following a monthly release cadence. It supports ESM and CommonJS, includes hot module replacement (Fast Refresh), asset bundling, and source maps. Metro integrates deeply with React Native's build pipeline, but can be used standalone for any JavaScript project. Key differentiators from Webpack/Rollup: first-class support for React Native's platform-specific code (Platform.OS), inline require, and transformer caching.","status":"active","version":"0.45.6-vjpr.3","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/facebook/metro","tags":["javascript"],"install":[{"cmd":"npm install metro-pnpm","lang":"bash","label":"npm"},{"cmd":"yarn add metro-pnpm","lang":"bash","label":"yarn"},{"cmd":"pnpm add metro-pnpm","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core bundler logic","package":"metro","optional":false},{"reason":"Configuration utilities","package":"metro-config","optional":false},{"reason":"Core utilities (caching, dependency graph)","package":"metro-core","optional":false},{"reason":"Default Babel preset for React Native","package":"metro-react-native-babel-preset","optional":false},{"reason":"Module resolution logic","package":"metro-resolver","optional":false},{"reason":"Source map generation","package":"metro-source-map","optional":false},{"reason":"Code transformation pipeline","package":"metro-transform-worker","optional":false}],"imports":[{"note":"ESM-only since v0.80.0. Use dynamic import for CJS or upgrade Node.js.","wrong":"const Metro = require('metro')","symbol":"metro default","correct":"import Metro from 'metro'"},{"note":"mergeConfig is exported from metro-config, not metro core.","wrong":"import { mergeConfig } from 'metro'","symbol":"mergeConfig","correct":"import { mergeConfig } from 'metro-config'"},{"note":"TypeScript users should import the type for type-checking; avoid redeclaring.","wrong":"interface MetroConfig { ... }","symbol":"MetroConfig","correct":"import type { MetroConfig } from 'metro-config'"},{"note":"Metro is a bundler CLI and library; importing via require is deprecated since v0.80.0.","wrong":"const Metro = require('metro')","symbol":"require","correct":"// Not used; Metro is a dev tool invoked via CLI or API"}],"quickstart":{"code":"import Metro from 'metro';\nimport { loadConfig, mergeConfig } from 'metro-config';\n\nconst config = await loadConfig();\nconst updatedConfig = mergeConfig(config, {\n  transformer: {\n    babelTransformerPath: require.resolve('metro-react-native-babel-transformer'),\n  },\n});\n\nconst { bundle } = await Metro.runBuild(updatedConfig, {\n  entry: 'index.js',\n  out: '/tmp/bundle.js',\n  platform: 'android',\n  dev: true,\n});\n\nconsole.log('Bundle built!');","lang":"typescript","description":"Loads default Metro config, merges custom transformer, and builds a bundle for Android in development mode."},"warnings":[{"fix":"Upgrade Node.js to v20.19 or later, or v22 LTS.","message":"Node v21 and v23 support dropped. Minimum Node v20.19 LTS.","severity":"breaking","affected_versions":">=0.84.0"},{"fix":"Use import() or set type: module in package.json. Alternatively, downgrade to Metro 0.79.x.","message":"ESM-only export from 'metro' requires dynamic import or native ESM. CommonJS require no longer works.","severity":"breaking","affected_versions":">=0.80.0"},{"fix":"Replace `enhanceMiddleware` with server.use in metro.config.js.","message":"`server.enhanceMiddleware` deprecated. Use `server.use` instead.","severity":"deprecated","affected_versions":">=0.83.0"},{"fix":"Ensure config export is synchronous or wraps errors. Use `metro.config.js` (CJS) or `metro.config.mjs` (ESM).","message":"Config file must export a plain object or a function returning an object. Async configs supported since 0.83.3, but accidental Promise rejection breaks startup.","severity":"gotcha","affected_versions":">=0.78.0"},{"fix":"Add custom resolver if needed. Do not rely on Babel plugins for platform-specific resolution.","message":"Platform-specific file extensions (`.ios.js`, `.android.js`) are resolved by Metro, not Babel. Misconfigured resolver may miss files.","severity":"gotcha","affected_versions":"*"},{"fix":"Remove explicit dependency on `metro-react-native-babel-preset` and rely on Metro's built-in preset.","message":"`metro-react-native-babel-preset` was previously a separate package; now bundled with Metro. Installing separately may cause version conflicts.","severity":"deprecated","affected_versions":">=0.83.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Add react-native to package.json and run npm install. If using monorepo, ensure Metro's watchFolders includes the root.","cause":"Missing react-native dependency or misconfigured module resolution.","error":"Error: Could not resolve module 'react-native'"},{"fix":"Use `import { loadConfig } from 'metro-config'`.","cause":"Importing loadConfig from 'metro' instead of 'metro-config'.","error":"TypeError: Metro.loadConfig is not a function"},{"fix":"Install `npm install --save-dev metro-react-native-babel-transformer` and set `transformer.babelTransformerPath` in config.","cause":"Metro cannot locate the Babel transformer. Missing dependency or misconfigured transformerPath.","error":"Error: Cannot find module 'metro-react-native-babel-transformer'"},{"fix":"Rename file to .mjs or add 'type':'module' to package.json. Alternatively, transpile with Babel.","cause":"Using ESM syntax in a CommonJS file (no 'type':'module' or .mjs extension).","error":"ParseError: 'import' and 'export' may only appear at the top level"},{"fix":"Start Metro with `npx react-native start` or set `server.port` in config. Kill other processes on port 8081.","cause":"Metro server not running or port conflict.","error":"Error: Opening IPC connection to Metro server failed"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}