Metro Configuration Reference

Complete reference for configuring Metro bundler in Expo projects.

Metro is the JavaScript bundler for React Native. Expo provides enhanced Metro configuration with additional features and optimizations.

Getting Started

Create a metro.config.js file in your project root:

// Learn more: https://docs.expo.dev/guides/customizing-metro
const { getDefaultConfig } = require('expo/metro-config');

/** @type {import('expo/metro-config').MetroConfig} */
const config = getDefaultConfig(__dirname);

module.exports = config;

Default Configuration

Expo’s default Metro config includes:

• Asset extensions for images, fonts, and other files
• Source extensions for .js, .jsx, .ts, .tsx, .json
• Transformer configuration for React Native and web
• Resolver configuration for React Native platform resolution
• Support for package.json exports field
• CSS and styled-components support for web
• Environment variable support

Configuration Options

Resolver Options

Control how Metro resolves modules.

assetExts

resolver.assetExts · string[]

File extensions to treat as assets.

const config = getDefaultConfig(__dirname);

config.resolver.assetExts.push('db', 'mp3', 'ttf', 'obj', 'png', 'jpg');

module.exports = config;

sourceExts

resolver.sourceExts · string[]

File extensions to treat as source code.

const config = getDefaultConfig(__dirname);

config.resolver.sourceExts.push('mjs', 'cjs');

module.exports = config;

When adding to sourceExts, ensure the extension isn’t already in assetExts.

platforms

resolver.platforms · string[]

Supported platform extensions.

config.resolver.platforms = ['ios', 'android', 'web', 'native'];

nodeModulesPaths

resolver.nodeModulesPaths · string[]

Additional directories to search for modules.

const path = require('path');

config.resolver.nodeModulesPaths = [
  path.resolve(__dirname, 'node_modules'),
  path.resolve(__dirname, '../node_modules'),
];

resolveRequest

resolver.resolveRequest · function

Custom resolution function.

config.resolver.resolveRequest = (context, moduleName, platform) => {
  // Custom resolution logic
  if (moduleName === 'my-custom-module') {
    return {
      filePath: path.resolve(__dirname, 'custom-module.js'),
      type: 'sourceFile',
    };
  }
  
  // Fall back to default resolution
  return context.resolveRequest(context, moduleName, platform);
};

unstable_enablePackageExports

resolver.unstable_enablePackageExports · boolean · default: "true"

Enable support for package.json exports field.

config.resolver.unstable_enablePackageExports = true;

unstable_conditionNames

resolver.unstable_conditionNames · string[]

Condition names for package exports resolution.

config.resolver.unstable_conditionNames = ['require', 'import', 'react-native'];

Transformer Options

Control how Metro transforms code.

babelTransformerPath

transformer.babelTransformerPath · string

Path to the Babel transformer.

config.transformer.babelTransformerPath = require.resolve(
  './custom-babel-transformer.js'
);

minifierPath

transformer.minifierPath · string

Path to the minifier. Defaults to Metro’s minifier.

config.transformer.minifierPath = require.resolve('metro-minify-terser');

minifierConfig

transformer.minifierConfig · object

Configuration for the minifier.

config.transformer.minifierConfig = {
  compress: {
    drop_console: true,
  },
};

getTransformOptions

transformer.getTransformOptions · function

Function returning transform options per bundle.

config.transformer.getTransformOptions = async () => ({
  transform: {
    experimentalImportSupport: false,
    inlineRequires: true,
  },
});

assetPlugins

transformer.assetPlugins · string[]

Asset plugins to use during transformation.

config.transformer.assetPlugins = [
  require.resolve('./my-asset-plugin.js'),
];

Server Options

Configure the Metro development server.

port

server.port · number · default: "8081"

Port to run Metro on.

config.server.port = 8082;

enhanceMiddleware

server.enhanceMiddleware · function

Add custom middleware to the Metro server.

config.server.enhanceMiddleware = (middleware, server) => {
  return (req, res, next) => {
    // Custom middleware logic
    if (req.url === '/custom-endpoint') {
      res.writeHead(200, { 'Content-Type': 'application/json' });
      res.end(JSON.stringify({ custom: true }));
      return;
    }
    
    return middleware(req, res, next);
  };
};

Watcher Options

Configure file watching behavior.

watchFolders

watchFolders · string[]

Additional folders for Metro to watch.

const path = require('path');

config.watchFolders = [
  path.resolve(__dirname, '../shared-package'),
];

Useful for monorepos where packages are outside the project directory.

hasteMapModulePath

hasteMapModulePath · string

Path to custom Haste map implementation.

Expo-Specific Features

Environment Variables

Expo automatically supports environment variables:

// Access in your app
const apiUrl = process.env.EXPO_PUBLIC_API_URL;

Only variables prefixed with EXPO_PUBLIC_ are available in your app.

CSS Support (Web)

Expo’s Metro config includes CSS support for web:

import './styles.css';

Asset Handling

Import assets directly:

import logo from './assets/logo.png';

<Image source={logo} />

Platform-Specific Extensions

Metro resolves platform-specific files automatically:

• Button.ios.tsx - iOS only
• Button.android.tsx - Android only
• Button.web.tsx - Web only
• Button.native.tsx - iOS and Android
• Button.tsx - All platforms (fallback)

Common Customizations

Adding SVG Support

npx expo install react-native-svg

const { getDefaultConfig } = require('expo/metro-config');
const { withNativeWind } = require('nativewind/metro');

const config = getDefaultConfig(__dirname);

config.transformer.babelTransformerPath = require.resolve(
  'react-native-svg-transformer'
);

config.resolver.assetExts = config.resolver.assetExts.filter(
  (ext) => ext !== 'svg'
);

config.resolver.sourceExts.push('svg');

module.exports = config;

Monorepo Configuration

const { getDefaultConfig } = require('expo/metro-config');
const path = require('path');

const projectRoot = __dirname;
const workspaceRoot = path.resolve(projectRoot, '../..');

const config = getDefaultConfig(projectRoot);

// Watch all files in the monorepo
config.watchFolders = [workspaceRoot];

// Let Metro know where to resolve packages
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];

module.exports = config;

Web-Specific Configuration

const { getDefaultConfig } = require('expo/metro-config');

const config = getDefaultConfig(__dirname);

// Add web-specific extensions
config.resolver.sourceExts.push('web.js', 'web.jsx', 'web.ts', 'web.tsx');

module.exports = config;

Custom Babel Configuration

Metro uses babel.config.js for transformation:

module.exports = function (api) {
  api.cache(true);
  return {
    presets: ['babel-preset-expo'],
    plugins: [
      // Your custom plugins
      'react-native-reanimated/plugin',
    ],
  };
};

See Babel Preset Reference for more.

Extending the Babel Transformer

Create a custom transformer:

// custom-babel-transformer.js
const expoTransformer = require('@expo/metro-config/babel-transformer');

module.exports.transform = function (src, filename, options) {
  // Custom transformation
  if (filename.endsWith('.custom.js')) {
    // Do custom transformation
  }
  
  // Use Expo's transformer
  return expoTransformer.transform(src, filename, options);
};

Then reference it:

const config = getDefaultConfig(__dirname);

config.transformer.babelTransformerPath = require.resolve(
  './custom-babel-transformer.js'
);

module.exports = config;

Performance Optimization

Cache Configuration

config.cacheStores = [
  new FileStore({
    root: path.join(__dirname, '.cache/metro'),
  }),
];

Worker Configuration

config.maxWorkers = 4; // Limit concurrent workers

Transform Caching

config.transformer.enableBabelRCLookup = false; // Skip .babelrc lookups
config.transformer.enableBabelRuntime = true; // Use Babel runtime

Troubleshooting

Clear Metro Cache

npx expo start --clear

Reset Metro

rm -rf node_modules/.cache/metro
npx expo start --clear

Debug Metro Configuration

Log the full configuration:

const config = getDefaultConfig(__dirname);

console.log(JSON.stringify(config, null, 2));

module.exports = config;

TypeScript Support

Metro automatically supports TypeScript with no configuration:

// Works out of the box
import { Component } from './Component';

Configure TypeScript in tsconfig.json, not Metro.

Source Maps

Metro generates source maps automatically in development. For production:

config.serializer.sourceMapUrl = 'http://localhost:8081/index.map';

Related Documentation

• Babel Preset Reference
• CLI Reference
• Metro Bundler Docs
• Customizing Metro