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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
getDefaultConfig
✓ import { getDefaultConfig } from 'metro-config';
✗ const { getDefaultConfig } = require('metro');
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.
mergeConfig
✓ import { mergeConfig } from 'metro-config';
✗ const { mergeConfig } = require('metro/config');
`mergeConfig` is used to combine Metro configuration objects, especially when extending default configs.
MetroConfig
✓ import type { MetroConfig } from 'metro-config';
Type definitions for Metro configuration are available from `metro-config` for TypeScript projects.
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`).
import path from 'path';
import { getDefaultConfig } from 'metro-config';
/**
* Metro configuration for a React Native project.
* See: https://facebook.github.io/metro/docs/configuration
*
* @type {import('metro-config').MetroConfig}
*/
const config = (async () => {
const { resolver: { sourceExts, assetExts } } = await getDefaultConfig(__dirname);
return {
transformer: {
babelTransformerPath: require.resolve('metro-react-native-babel-transformer'),
enableBabelRCLookup: true,
// Optionally customize babel transformer options
// getTransformOptions: async () => ({
// transform: {
// experimentalImportSupport: false,
// inlineRequires: true,
// },
// }),
},
resolver: {
assetExts: [...assetExts, 'gltf', 'glb', 'bin', 'webp', 'mp3', 'mp4'],
sourceExts: [...sourceExts, 'mjs', 'cjs', 'ts', 'tsx'],
},
server: {
port: process.env.METRO_PORT ? parseInt(process.env.METRO_PORT, 10) : 8081,
// Enable HTTPS server with your own key and certificate:
// https: {
// key: path.resolve(__dirname, './ssl/key.pem'),
// cert: path.resolve(__dirname, './ssl/cert.pem'),
// },
},
// Add additional directories to watch for changes, useful in monorepos.
watchFolders: [
// path.resolve(__dirname, '../../packages/my-shared-components'),
],
// Cache configuration (defaults to FileStore).
cacheStores: [],
};
})();
module.exports = config;
metro --version
Debug
Known issues
breakingMetro `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.fixEnsure your Node.js environment is `^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0` or upgrade to a compatible version.
affects: >=0.84.0
gotchaTypeScript 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.fixUpgrade 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`.
affects: <0.83.5, >=0.83.5 <0.84.2
gotchaEnabling 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.fixProvide 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.
affects: >=0.83.5 || >=0.84.1
gotchaRegressions 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.fixUpgrade 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.
affects: <0.83.3
gotchaSupport 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`).fixEnsure 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.
affects: >=0.83.2
Errors
Common errors & fixes
Error: Requires Node.js ^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0
Metro is being run with an incompatible or unsupported Node.js version.
fixUpgrade or downgrade your Node.js installation to meet the specified engine requirements (`^20.19.4 || ^22.13.0 || ^24.3.0 || >= 25.0.0`).
Error: The transform cache was not invalidated correctly.
Metro's transformer cache did not correctly include user-defined Babel configuration, leading to stale bundles or incorrect transformations.
fixUpgrade 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`.
Metro config file not found or is invalid.
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.
fixVerify 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.
TypeError: Cannot read properties of undefined (reading 'transform') (or similar during bundling)
This often indicates an issue with the Babel transformer configuration, such as an incorrect `babelTransformerPath` or missing `metro-react-native-babel-transformer` package.
fixEnsure `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')`). Audit
Dependencies
No dependency data recorded yet.