{"id":11305,"library":"metro","title":"Metro Bundler for React Native","description":"Metro is the JavaScript bundler specifically designed for React Native applications, providing optimized bundling, hot module reloading (HMR), and Fast Refresh capabilities crucial for efficient mobile development workflows. It is currently at version 0.84.3 and typically sees frequent minor releases, incorporating new features, bug fixes, and performance improvements. Key differentiators include its deep integration with the React Native ecosystem, advanced caching mechanisms for fast rebuilds, and robust support for various configuration options, including CommonJS, ESM, and TypeScript configuration files. Metro focuses on delivering a high-performance and streamlined developer experience, enabling rapid iteration cycles for large-scale React Native projects. It requires Node.js versions ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0.","status":"active","version":"0.84.3","language":"javascript","source_language":"en","source_url":"https://github.com/facebook/metro","tags":["javascript","typescript"],"install":[{"cmd":"npm install metro","lang":"bash","label":"npm"},{"cmd":"yarn add metro","lang":"bash","label":"yarn"},{"cmd":"pnpm add metro","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"Configuration utilities like `getDefaultConfig` are typically imported from `metro-config`, not the main `metro` package. Use ES Modules syntax in TypeScript or modern Node.js.","wrong":"const { getDefaultConfig } = require('metro');","symbol":"getDefaultConfig","correct":"import { getDefaultConfig } from 'metro-config';"},{"note":"`mergeConfig` is used to combine Metro configuration objects, especially when extending default configs.","wrong":"const { mergeConfig } = require('metro/config');","symbol":"mergeConfig","correct":"import { mergeConfig } from 'metro-config';"},{"note":"Type definitions for Metro configuration are available from `metro-config` for TypeScript projects.","symbol":"MetroConfig","correct":"import type { MetroConfig } from 'metro-config';"}],"quickstart":{"code":"import path from 'path';\nimport { getDefaultConfig } from 'metro-config';\n\n/**\n * Metro configuration for a React Native project.\n * See: https://facebook.github.io/metro/docs/configuration\n *\n * @type {import('metro-config').MetroConfig}\n */\nconst config = (async () => {\n  const { resolver: { sourceExts, assetExts } } = await getDefaultConfig(__dirname);\n\n  return {\n    transformer: {\n      babelTransformerPath: require.resolve('metro-react-native-babel-transformer'),\n      enableBabelRCLookup: true,\n      // Optionally customize babel transformer options\n      // getTransformOptions: async () => ({\n      //   transform: {\n      //     experimentalImportSupport: false,\n      //     inlineRequires: true,\n      //   },\n      // }),\n    },\n    resolver: {\n      assetExts: [...assetExts, 'gltf', 'glb', 'bin', 'webp', 'mp3', 'mp4'],\n      sourceExts: [...sourceExts, 'mjs', 'cjs', 'ts', 'tsx'],\n    },\n    server: {\n      port: process.env.METRO_PORT ? parseInt(process.env.METRO_PORT, 10) : 8081,\n      // Enable HTTPS server with your own key and certificate:\n      // https: {\n      //   key: path.resolve(__dirname, './ssl/key.pem'),\n      //   cert: path.resolve(__dirname, './ssl/cert.pem'),\n      // },\n    },\n    // Add additional directories to watch for changes, useful in monorepos.\n    watchFolders: [\n      // path.resolve(__dirname, '../../packages/my-shared-components'),\n    ],\n    // Cache configuration (defaults to FileStore).\n    cacheStores: [],\n  };\n})();\n\nmodule.exports = config;\n","lang":"typescript","description":"Demonstrates a typical `metro.config.js` file for a React Native project, showing how to customize transformer, resolver, and server settings while extending Metro's default configuration. This file is typically run via the React Native CLI (e.g., `npx react-native start`)."},"warnings":[{"fix":"Ensure your Node.js environment is `^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0` or upgrade to a compatible version.","message":"Metro `v0.84.0` introduced breaking changes by dropping support for older Node.js versions. Specifically, Node.js v21, v23, and LTS minors released before v20.19 are no longer supported.","severity":"breaking","affected_versions":">=0.84.0"},{"fix":"Upgrade to Metro `v0.83.5` or `v0.84.2` or later to ensure correct TypeScript type publication. If issues persist, verify `metro-config` version or reinstall `node_modules`.","message":"TypeScript type declarations have intermittently faced issues with publication in certain minor releases (e.g., in v0.83.x before v0.83.5 and v0.84.x before v0.84.2), leading to missing types or compilation errors in TypeScript projects.","severity":"gotcha","affected_versions":"<0.83.5, >=0.83.5 <0.84.2"},{"fix":"Provide valid absolute paths to your SSL private key (`key.pem`) and certificate (`cert.pem`) files in your `metro.config.js`. Ensure the files are readable by the Metro process.","message":"Enabling Metro's HTTPS server via `config.server.tls` (added in `v0.83.5` and `v0.84.1`) requires correctly configured SSL `key` and `cert` paths. Incorrect paths or malformed files will prevent the server from starting.","severity":"gotcha","affected_versions":">=0.83.5 || >=0.84.1"},{"fix":"Upgrade Metro to `v0.83.3` or later to benefit from fixes related to config file parsing and merging. Simplify complex config exports if an upgrade is not immediately possible.","message":"Regressions in config file loading, such as issues with config files exporting promises or incorrect merging of multiple partial configs, have been observed and fixed in earlier `v0.83.x` releases. Using complex config logic on older versions might lead to unexpected behavior.","severity":"gotcha","affected_versions":"<0.83.3"},{"fix":"Ensure your Node.js version supports native TypeScript execution, or integrate a tool like `ts-node` into your development workflow for `.ts` config files. Alternatively, use a `.js` config file.","message":"Support for TypeScript `metro.config.ts` files (introduced in `v0.83.2`) relies on the underlying Node.js or Bun version's native TypeScript support. If your environment does not natively support `.ts` execution, you may need additional setup (e.g., `ts-node`).","severity":"gotcha","affected_versions":">=0.83.2"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Upgrade or downgrade your Node.js installation to meet the specified engine requirements (`^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0`).","cause":"Metro is being run with an incompatible or unsupported Node.js version.","error":"Error: Requires Node.js ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0"},{"fix":"Upgrade Metro to `v0.83.6` or newer. If an immediate upgrade is not feasible, try clearing Metro's cache manually by running `npx react-native start --reset-cache` or `npx metro serve --reset-cache`.","cause":"Metro's transformer cache did not correctly include user-defined Babel configuration, leading to stale bundles or incorrect transformations.","error":"Error: The transform cache was not invalidated correctly."},{"fix":"Verify that `metro.config.js` exists in the project root or `.config/` directory. Check the file for syntax errors and ensure it exports a valid Metro configuration object or a promise that resolves to one. Ensure any required paths are correctly resolved.","cause":"Metro could not locate `metro.config.js` (or `.mjs`, `.ts`) in the expected locations, or the file contains syntax errors, or does not export a valid configuration object/promise.","error":"Metro config file not found or is invalid."},{"fix":"Ensure `metro-react-native-babel-transformer` is installed (`npm install metro-react-native-babel-transformer`) and `babelTransformerPath` in `metro.config.js` correctly points to its resolved path (`require.resolve('metro-react-native-babel-transformer')`).","cause":"This often indicates an issue with the Babel transformer configuration, such as an incorrect `babelTransformerPath` or missing `metro-react-native-babel-transformer` package.","error":"TypeError: Cannot read properties of undefined (reading 'transform') (or similar during bundling)"}],"ecosystem":"npm"}