Metro Bundler Expert

Comprehensive expertise in React Native's Metro bundler, including configuration, optimization, custom transformers, caching strategies, and troubleshooting common bundling issues.

What I Know

Metro Fundamentals

What is Metro?

JavaScript bundler for React Native
Transforms and bundles JavaScript modules
Handles assets (images, fonts, etc.)
Provides fast refresh for development
Generates source maps for debugging

Key Concepts

Transformer: Converts source code (TypeScript, JSX) to JavaScript
Resolver: Locates modules in the file system
Serializer: Combines modules into bundles
Cache: Speeds up subsequent builds

Metro Configuration

Basic metro.config.js

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

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

module.exports = config;

Custom Configuration

const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');

const defaultConfig = getDefaultConfig(__dirname);

const config = {
  transformer: {
    // Enable Babel transformer
    babelTransformerPath: require.resolve('react-native-svg-transformer'),

    // Source map options
    getTransformOptions: async () => ({
      transform: {
        experimentalImportSupport: false,
        inlineRequires: true,
      },
    }),
  },

  resolver: {
    // Custom asset extensions
    assetExts: defaultConfig.resolver.assetExts.filter(ext => ext !== 'svg'),

    // Custom source extensions
    sourceExts: [...defaultConfig.resolver.sourceExts, 'svg', 'cjs'],

    // Node module resolution
    nodeModulesPaths: [
      './node_modules',
      '../../node_modules',  // For monorepos
    ],

    // Custom platform-specific extensions
    platforms: ['ios', 'android', 'native'],
  },

  server: {
    // Custom port
    port: 8081,

    // Enhanced logging
    enhanceMiddleware: (middleware) => {
      return (req, res, next) => {
        console.log(`Metro request: ${req.url}`);
        return middleware(req, res, next);
      };
    },
  },

  watchFolders: [
    // Watch external folders (monorepos)
    path.resolve(__dirname, '..', 'shared-library'),
  ],

  resetCache: true,  // Reset cache on start (dev only)
};

module.exports = mergeConfig(defaultConfig, config);

Optimization Strategies

Inline Requires

// metro.config.js
module.exports = {
  transformer: {
    getTransformOptions: async () => ({
      transform: {
        inlineRequires: true,  // Lazy load modules (faster startup)
      },
    }),
  },
};

// Before (eager loading)
import UserProfile from './UserProfile';
import Settings from './Settings';

function App() {
  return (
    <View>
      {showProfile ? <UserProfile /> : <Settings />}
    </View>
  );
}

// After inline requires (lazy loading)
function App() {
  return (
    <View>
      {showProfile ?
        <require('./UserProfile').default /> :
        <require('./Settings').default />
      }
    </View>
  );
}

Bundle Splitting (Experimental)

// metro.config.js
module.exports = {
  serializer: {
    createModuleIdFactory: () => {
      // Generate stable module IDs for better caching
      return (path) => {
        return require('crypto')
          .createHash('sha1')
          .update(path)
          .digest('hex')
          .substring(0, 8);
      };
    },
  },
};

Asset Optimization

// metro.config.js
module.exports = {
  transformer: {
    // Minify assets
    minifierPath: require.resolve('metro-minify-terser'),
    minifierConfig: {
      compress: {
        drop_console: true,  // Remove console.log in production
        drop_debugger: true,
      },
      output: {
        comments: false,
      },
    },
  },

  resolver: {
    // Optimize asset resolution
    assetExts: [
      'png', 'jpg', 'jpeg', 'gif', 'webp',  // Images
      'mp3', 'wav', 'm4a', 'aac',           // Audio
      'mp4', 'mov',                          // Video
      'ttf', 'otf', 'woff', 'woff2',        // Fonts
    ],
  },
};

Custom Transformers

SVG Transformer

# Install
npm install react-native-svg react-native-svg-transformer

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

const config = getDefaultConfig(__dirname);

config.transformer = {
  ...config.transformer,
  babelTransformerPath: require.resolve('react-native-svg-transformer'),
};

config.resolver = {
  ...config.resolver,
  assetExts: config.resolver.assetExts.filter(ext => ext !== 'svg'),
  sourceExts: [...config.resolver.sourceExts, 'svg'],
};

module.exports = config;

// Usage in code
import Logo from './assets/logo.svg';

function App() {
  return <Logo width={120} height={40} />;
}

Multiple File Extensions

// metro.config.js
module.exports = {
  resolver: {
    // Add .web.js, .native.js for platform-specific code
    sourceExts: ['js', 'json', 'ts', 'tsx', 'jsx', 'web.js', 'native.js'],

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

      return context.resolveRequest(context, moduleName, platform);
    },
  },
};

Caching Strategies

Cache Management

# Clear Metro cache
npx react-native start --reset-cache
npm start -- --reset-cache  # Expo

# Or manually
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*

# Clear watchman cache
watchman watch-del-all

# Clear all caches (nuclear option)
npm run clear  # If configured in package.json

Cache Configuration

// metro.config.js
const path = require('path');

module.exports = {
  cacheStores: [
    // Custom cache directory
    {
      get: (key) => {
        const cachePath = path.join(__dirname, '.metro-cache', key);
        // Implement custom cache retrieval
      },
      set: (key, value) => {
        const cachePath = path.join(__dirname, '.metro-cache', key);
        // Implement custom cache storage
      },
    },
  ],

  // Reset cache on config changes
  resetCache: process.env.RESET_CACHE === 'true',
};

Monorepo Setup

Workspaces Configuration

// metro.config.js (in app directory)
const path = require('path');
const { getDefaultConfig } = require('@react-native/metro-config');

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

const config = getDefaultConfig(projectRoot);

// Watch workspace directories
config.watchFolders = [workspaceRoot];

// Resolve modules from workspace
config.resolver.nodeModulesPaths = [
  path.resolve(projectRoot, 'node_modules'),
  path.resolve(workspaceRoot, 'node_modules'),
];

// Avoid hoisting issues
config.resolver.disableHierarchicalLookup = false;

module.exports = config;

Symlink Handling

// metro.config.js
module.exports = {
  resolver: {
    // Enable symlink support
    unstable_enableSymlinks: true,

    // Resolve symlinked packages
    resolveRequest: (context, moduleName, platform) => {
      const resolution = context.resolveRequest(context, moduleName, platform);

      if (resolution && resolution.type === 'sourceFile') {
        // Resolve real path for symlinks
        const realPath = require('fs').realpathSync(resolution.filePath);
        return {
          ...resolution,
          filePath: realPath,
        };
      }

      return resolution;
    },
  },
};

Common Issues & Solutions

"Unable to resolve module"

# Solution 1: Clear cache
npx react-native start --reset-cache

# Solution 2: Reinstall dependencies
rm -rf node_modules
npm install

# Solution 3: Check import paths
# Ensure case-sensitive imports match file names
import UserProfile from './userProfile';  # ❌ Wrong case
import UserProfile from './UserProfile';  # ✅ Correct

# Solution 4: Add to metro.config.js
module.exports = {
  resolver: {
    extraNodeModules: {
      'my-module': path.resolve(__dirname, 'node_modules/my-module'),
    },
  },
};

"Port 8081 already in use"

# Find and kill process
lsof -ti:8081 | xargs kill -9

# Or start on different port
npx react-native start --port 8082

# Update code to use new port
adb reverse tcp:8082 tcp:8082  # Android

"Invariant Violation: Module AppRegistry is not a registered callable module"

# Clear all caches
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
watchman watch-del-all
rm -rf node_modules
npm install
npx react-native start --reset-cache

"TransformError: ... SyntaxError"

// Add Babel plugin to metro.config.js
module.exports = {
  transformer: {
    babelTransformerPath: require.resolve('./customBabelTransformer.js'),
  },
};

// customBabelTransformer.js
module.exports = require('metro-react-native-babel-preset');

When to Use This Skill

Ask me when you need help with:

Configuring Metro bundler
Custom transformers (SVG, images, etc.)
Optimizing bundle size and startup time
Setting up monorepo with Metro
Troubleshooting "Unable to resolve module" errors
Clearing Metro cache effectively
Configuring source maps
Platform-specific file resolution
Debugging bundling performance
Custom asset handling
Port conflicts (8081)
Symlink resolution in monorepos

Essential Commands

Development

# Start Metro bundler
npx react-native start

# Start with cache cleared
npx react-native start --reset-cache

# Start with custom port
npx react-native start --port 8082

# Start with verbose logging
npx react-native start --verbose

# Expo dev server
npx expo start

# Expo with cache cleared
npx expo start -c

Debugging

# Check Metro status
curl http://localhost:8081/status

# Get bundle (for debugging)
curl http://localhost:8081/index.bundle?platform=ios > bundle.js

# Check source map
curl http://localhost:8081/index.map?platform=ios > bundle.map

# List all modules in bundle
curl http://localhost:8081/index.bundle?platform=ios&dev=false&minify=false

Cache Management

# Clear Metro cache
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*

# Clear watchman
watchman watch-del-all

# Clear all (comprehensive)
npm run clear  # Custom script
# Or manually:
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
watchman watch-del-all
rm -rf node_modules
npm install

Pro Tips & Tricks

1. Bundle Analysis

Analyze bundle size to find optimization opportunities:

# Generate bundle with source map
npx react-native bundle \
  --platform ios \
  --dev false \
  --entry-file index.js \
  --bundle-output ./bundle.js \
  --sourcemap-output ./bundle.map

# Analyze with source-map-explorer
npm install -g source-map-explorer
source-map-explorer bundle.js bundle.map

2. Environment-Specific Configuration

// metro.config.js
const isDev = process.env.NODE_ENV !== 'production';

module.exports = {
  transformer: {
    minifierConfig: {
      compress: {
        drop_console: !isDev,  // Remove console.log in production
      },
    },
  },

  serializer: {
    getModulesRunBeforeMainModule: () => [
      // Polyfills for production
      ...(!isDev ? [require.resolve('./polyfills.js')] : []),
    ],
  },
};

3. Custom Asset Pipeline

// metro.config.js
module.exports = {
  transformer: {
    // Optimize images during bundling
    assetPlugins: ['expo-asset/tools/hashAssetFiles'],
  },

  resolver: {
    assetExts: ['png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'],

    // Custom asset resolution
    resolveAsset: (dirPath, assetName, extension) => {
      const basePath = `${dirPath}/${assetName}`;

      // Try @2x, @3x variants
      const variants = ['@3x', '@2x', ''];
      for (const variant of variants) {
        const path = `${basePath}${variant}.${extension}`;
        if (require('fs').existsSync(path)) {
          return path;
        }
      }

      return null;
    },
  },
};

4. Preloading Heavy Modules

// index.js
import { AppRegistry } from 'react-native';
import App from './App';

// Preload heavy modules
import('./src/heavyModule').then(() => {
  console.log('Heavy module preloaded');
});

AppRegistry.registerComponent('MyApp', () => App);

5. Development Performance Boost

// metro.config.js
const isDev = process.env.NODE_ENV !== 'production';

module.exports = {
  transformer: {
    // Skip minification in dev
    minifierPath: isDev ? undefined : require.resolve('metro-minify-terser'),

    // Faster source maps in dev
    getTransformOptions: async () => ({
      transform: {
        inlineRequires: !isDev,  // Only in production
      },
    }),
  },

  server: {
    // Increase file watching performance
    watchFolders: isDev ? [] : undefined,
  },
};

Integration with SpecWeave

Configuration Management

Document Metro configuration in docs/internal/architecture/
Track bundle size across increments
Include bundling optimization in tasks.md

Performance Monitoring

Set bundle size thresholds
Track startup time improvements
Document optimization strategies

Troubleshooting

Maintain runbook for common Metro issues
Document cache clearing procedures
Track bundling errors in increment reports

metro-bundler