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-config').getDefaultConfig
Used to retrieve the default Metro configuration, often as a base for custom configs.
mergeConfig
✓ import { mergeConfig } from 'metro-config'
✗ const mergeConfig = require('metro-config').mergeConfig
Utility function to deeply merge two or more Metro configuration objects, handling arrays and objects correctly.
defineConfig
✓ import { defineConfig } from 'metro-config'
✗ import defineConfig from 'metro-config'
A type-safe helper for defining your Metro configuration, especially useful in TypeScript files (e.g., `metro.config.ts`).
MetroConfig
✓ import type { MetroConfig } from 'metro-config'
Imports the TypeScript type definition for the Metro configuration object.
This quickstart demonstrates a typical `metro.config.ts` file, showing how to import and use `getDefaultConfig`, `mergeConfig`, and `defineConfig` to customize Metro's behavior, including transformer options, asset/source extensions, and server settings. It handles both simple projects and monorepo setups.
import { getDefaultConfig, mergeConfig, defineConfig } from 'metro-config';
import type { MetroConfig } from 'metro-config';
const projectRoot = __dirname;
const workspaceRoot = process.env.WORKSPACE_ROOT ?? projectRoot; // For monorepos
const config: MetroConfig = defineConfig({
projectRoot,
watchFolders: [
projectRoot,
// For monorepos, you might add parent directories or other package folders
// workspaceRoot
],
transformer: {
babelTransformerPath: require.resolve('metro-react-native-babel-transformer'),
getTransformOptions: async () => ({
transform: {
experimentalImportSupport: false,
inlineRequires: true,
},
}),
},
resolver: {
assetExts: ['png', 'jpg', 'jpeg', 'gif', 'bmp', 'webp', 'svg', 'm4v', 'mov', 'mp4', 'aac', 'aiff', 'caf', 'm4a', 'mp3', 'wav', 'obj', 'mtl', 'gltf', 'glb', 'bin', 'arobject', 'reality'],
sourceExts: ['js', 'jsx', 'ts', 'tsx', 'json', 'mjs', 'cjs'],
nodeModulesPaths: [process.env.NODE_MODULES_PATH ?? './node_modules'], // Example for custom node_modules path
},
server: {
port: 8081,
// Example of enabling TLS/HTTPS for the Metro server
// tls: {
// key: Buffer.from(process.env.METRO_TLS_KEY ?? '', 'base64'),
// cert: Buffer.from(process.env.METRO_TLS_CERT ?? '', 'base64'),
// pfx: Buffer.from(process.env.METRO_TLS_PFX ?? '', 'base64'),
// passphrase: process.env.METRO_TLS_PASSPHRASE ?? '',
// }
},
});
module.exports = (async () => {
const defaultConfig = await getDefaultConfig();
return mergeConfig(defaultConfig, config);
})();
Debug
Known issues
breakingMetro Config v0.84.0 and later dropped support for several Node.js versions, specifically Node v21, v23, and LTS minors released before v20.19. Using an unsupported Node.js version will result in errors.fixUpgrade your Node.js environment to a supported version, such as Node.js ^20.19.4, ^22.13.0, ^24.3.0, or >= 25.0.0.
affects: >=0.84.0
gotchaTypeScript type declarations (`.d.ts` files) were accidentally omitted from npm publications in versions <=0.83.4 and <=0.84.1, leading to type errors in TypeScript projects.fixEnsure you are using `metro-config` version 0.83.5 or newer, or 0.84.2 or newer, to correctly receive the TypeScript types.
affects: <=0.83.4, <=0.84.1
gotchaSupport for ESM (`metro.config.mjs`) and TypeScript (`metro.config.ts`) configuration files was introduced in v0.83.2. Prior versions only supported CommonJS (`metro.config.js`). Attempting to use ESM/TS config files with older versions will fail.fixFor projects requiring ESM or TypeScript config files, upgrade `metro-config` to version 0.83.2 or later. Otherwise, use a CommonJS `metro.config.js` file.
affects: <0.83.2
gotchaThe `config.server.tls` option was added in v0.83.5 and v0.84.1 to configure Metro as an HTTPS server. This feature is not available in earlier versions.fixIf you need to expose Metro as an HTTPS server, ensure you are using `metro-config` version 0.83.5 or 0.84.1 or newer.
affects: <0.83.5, <0.84.1
Errors
Common errors & fixes
SyntaxError: Cannot use import statement outside a module
Your `metro.config.js` file is attempting to use ES module `import`/`export` syntax but is being treated as a CommonJS module. This can happen if Node.js isn't configured for ESM or if you're using an older Node.js version without explicit `.mjs` extension.
fixEither rename your config file to `metro.config.mjs` (for explicit ESM) or `metro.config.ts` (if using TypeScript with an appropriate `tsconfig.json` and Node.js version 16+), or convert your file to use CommonJS `require()` and `module.exports` syntax.
Error: Cannot find module 'metro-react-native-babel-transformer'
A custom `babelTransformerPath` or other transformer is specified in your `metro.config.js` but the corresponding package is not installed or incorrectly resolved.
fixEnsure the specified transformer package (e.g., `metro-react-native-babel-transformer` or `react-native-typescript-transformer`) is listed in your `package.json` and installed via `npm install` or `yarn install`.
TypeError: config is not a function or object
Your `metro.config.js` file is not exporting a valid Metro configuration object, a function that returns a configuration object, or a promise that resolves to one.
fixVerify that your `metro.config.js` correctly exports its configuration, typically via `module.exports = { ... }`, `module.exports = async () => ({ ... })`, or `export default { ... }` in an ESM context. Audit
Dependencies
No dependency data recorded yet.