React Native, Metro and Module Federation

This guide will explain how to build a React Native app with Metro bundler that uses Module Federation to share code between apps. This approach enables you to create micro-frontend architectures in React Native applications, allowing teams to develop, deploy, and scale mini-applications independently.

Prerequisites
  • Finished our Get Started guide
  • A registered account on Zephyr Cloud
  • npm >=10
  • node >=18
  • ruby >= 3.3.2
  • React 19 and React Native 0.79 or newer

Overview

Module Federation with Metro bundler in React Native provides several key advantages:

  1. Independent Development: Teams can develop mini-applications in isolation with their own release cycles
  2. Code Sharing: Efficient sharing of common dependencies and utilities across applications
  3. Runtime Loading: Dynamic loading of mini-applications without requiring app store updates
  4. Scalability: Easy addition of new features and micro-frontends as your application grows
  5. Team Autonomy: Different teams can work on different parts of the application independently

Architecture Considerations

When implementing Module Federation with Metro in React Native, consider these architectural patterns:

  • Host Application: The main React Native app that loads and orchestrates mini-applications
  • Mini Applications: Self-contained React Native applications that expose specific functionality
  • Shared Dependencies: Common libraries and utilities shared between host and mini-applications

Creating Your Applications

Project Structure

Your project structure should look like this:

apps/
├── HostApp/                # Main React Native application
│   ├── metro.config.js     # Metro configuration with Module Federation
│   ├── react-native.config.js
│   ├── package.json
│   └── src/
│       └── App.tsx
├── MiniApp/                # Mini application
│   ├── metro.config.js     # Metro configuration with Module Federation
│   ├── react-native.config.js
│   ├── package.json
│   └── src/
│       └── example.tsx     # Exposed component
└── libs/                   # Shared libraries (optional)
    └── core/               # Shared utilities and components

Creating a New React Native Application

If you're starting from scratch, create both the host and mini applications:

Create a new React Native host application:

npx @react-native-community/cli@latest init HostApp
cd HostApp

Create a new React Native mini application:

npx @react-native-community/cli@latest init MiniApp
cd MiniApp

Modifying an Existing React Native Application

If you have existing React Native applications, you can convert them to use Module Federation. Install the required dependencies in both host and mini applications:

npm
yarn
pnpm
bun
deno
npm add --dev zephyr-metro-plugin@^1.8.0 @module-federation/metro@^2.9.0 @module-federation/runtime

Configuring the Mini Application

The mini application is a self-contained React Native app that exposes specific functionality to be consumed by the host application. This section covers the essential configuration steps.

Understanding Mini Application Configuration

Mini applications in Module Federation work as "remotes" that expose modules to be consumed by host applications. Key aspects include:

  • Exposed Modules: Components, utilities, or entire screens that can be loaded by the host
  • Shared Dependencies: Libraries that are shared between host and mini applications
  • Bundle Configuration: How the application is bundled and served

Step 1: Configure Metro for Module Federation

Create or modify your metro.config.js file in the mini application:

// MiniApp/metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withModuleFederation } = require('@module-federation/metro');
const { withZephyr } = require('zephyr-metro-plugin');

/**
 * Metro configuration
 * https://reactnative.dev/docs/metro
 *
 * @type {import('@react-native/metro-config').MetroConfig}
 */
const config = {
  resolver: { useWatchman: false },
};

const mfConfig = {
  name: 'miniApp',
  filename: 'miniApp.bundle',
  exposes: {
    './example': './src/example.tsx',
  },
  shared: {
    react: {
      singleton: true,
      eager: false,
      requiredVersion: '19.1.0',
      version: '19.1.0',
      import: false,
    },
    'react-native': {
      singleton: true,
      eager: false,
      requiredVersion: '0.80.0',
      version: '0.80.0',
      import: false,
    },
  },
  shareStrategy: 'version-first',
};

async function getConfig() {
  const baseConfig = mergeConfig(getDefaultConfig(__dirname), config);
  const zephyrConfig = await withZephyr({
    name: mfConfig.name,
    target: process.env.ZEPHYR_TARGET === 'android' ? 'android' : 'ios',
  })(baseConfig);

  return withModuleFederation(zephyrConfig, mfConfig, {
    flags: {
      unstable_patchHMRClient: true,
      unstable_patchInitializeCore: true,
      unstable_patchRuntimeRequire: true,
    },
  });
}

module.exports = getConfig();

This configures Zephyr remote resolution and the local manifest, but it does not upload a bundle. See Metro configuration and publication for the lifecycle, Git-based identity inference, and an explicit zephyr.config.ts identity override.

Configuration Breakdown
  • name: Unique identifier for your mini application
  • filename: The bundle filename that will be generated
  • exposes: Modules to expose to host applications (key is the public path, value is the source path)
  • shared: Dependencies shared with the host application
    • singleton: Ensures only one instance is loaded
    • eager: Controls whether the dependency is loaded immediately
    • requiredVersion: Version constraint for the shared dependency
    • import: Whether to import the dependency (set to false for React Native)
  • shareStrategy: 'version-first' prioritizes version compatibility

Step 2: Register Publication Commands

Create react-native.config.js in both applications. The adapter registers the remote and host publication commands:

// MiniApp/react-native.config.js
const { zephyrMetroReactNativeCli } = require('zephyr-metro-plugin');

module.exports = zephyrMetroReactNativeCli();

If either application already has React Native CLI settings, merge the adapter commands instead of replacing the existing config. See React Native CLI publication commands for the preserving form.

Why This Configuration?

This configuration adds React Native CLI commands that:

  • Handle Module Federation bundling
  • Integrate with Zephyr Cloud for asset upload
  • Update the Module Federation manifest
  • Enable deployment to Zephyr's edge network

Step 3: Create an Exposed Component

Create a component in your mini application that will be exposed to the host:

// MiniApp/src/example.tsx
import React from 'react';
import { View, Text, StyleSheet } from 'react-native';

export default function Example() {
  return (
    <View style={styles.container}>
      <Text style={styles.text}>Hello from Mini App!</Text>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    padding: 20,
    backgroundColor: '#f0f0f0',
    borderRadius: 8,
  },
  text: {
    fontSize: 18,
    fontWeight: 'bold',
    color: '#333',
  },
});

Step 4: Bundle Your Mini Application

Once configured, bundle your mini application for each platform. A Zephyr environment serves a single version, and each version is built for one platform, so label the iOS and Android builds with separate environments:

# Bundle for iOS
ZE_ENV=yourEnvironment-ios npx react-native bundle-mf-remote --platform ios --dev false

# Bundle for Android
ZE_ENV=yourEnvironment-android npx react-native bundle-mf-remote --platform android --dev false
Tip

After the first bundle finishes, open the Zephyr Cloud dashboard and verify that the mini application exists with a new version. Then create the yourEnvironment-ios and yourEnvironment-android environments as described in Deploying to Specific Environments.

Configuring the Host Application

The host application is the main React Native app that loads and orchestrates mini-applications. It acts as a "consumer" in the Module Federation architecture.

Understanding Host Application Configuration

The host application configuration differs from mini-applications in several key ways:

  • Remotes Configuration: Defines which mini-applications to load and from where
  • Eager Loading: Host applications typically eager-load shared dependencies
  • Runtime Plugins: Can include custom runtime logic for module loading
  • Share Strategy: Uses 'loaded-first' strategy to prioritize already loaded dependencies

Step 1: Configure Metro for the Host

Create or modify your metro.config.js file in the host application:

// HostApp/metro.config.js
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const { withZephyr } = require('zephyr-metro-plugin');
const { withModuleFederation } = require('@module-federation/metro');

/**
 * Metro configuration
 * https://reactnative.dev/docs/metro
 *
 * @type {import('@react-native/metro-config').MetroConfig}
 */

const miniAppPort = process.env.MINI_APP_PORT ?? '8082';

const config = {
  resolver: { useWatchman: false },
};

const mfConfig = {
  name: 'hostApp',
  remotes: {
    miniApp: `miniApp@http://localhost:${miniAppPort}/mf-manifest.json`,
  },
  shared: {
    react: {
      singleton: true,
      eager: true,
      requiredVersion: '19.1.0',
      version: '19.1.0',
    },
    'react-native': {
      singleton: true,
      eager: true,
      requiredVersion: '0.80.0',
      version: '0.80.0',
    },
  },
  shareStrategy: 'loaded-first',
};

const getConfig = async () => {
  const baseConfig = mergeConfig(getDefaultConfig(__dirname), config);
  const zephyrConfig = await withZephyr({
    name: mfConfig.name,
    remotes: mfConfig.remotes,
    target: process.env.ZEPHYR_TARGET === 'android' ? 'android' : 'ios',
  })(baseConfig);

  return withModuleFederation(zephyrConfig, mfConfig, {
    flags: {
      unstable_patchHMRClient: true,
      unstable_patchInitializeCore: true,
      unstable_patchRuntimeRequire: true,
    },
  });
};

module.exports = getConfig();
Configuration Breakdown
  • name: Unique identifier for your host application
  • remotes: Mini-applications to load
    • Key is the local name you'll use to import
    • Value is the local manifest URL used during development. Zephyr builds replace it with the URL resolved from the matching zephyr:dependencies entry in the next step
  • shared: Dependencies shared with mini-applications
    • eager: true: Host loads these dependencies immediately
  • shareStrategy: 'loaded-first' prioritizes already loaded dependencies
  • runtimePlugins: Optional Module Federation runtime plugins for custom logic, such as zephyr-native-cache/runtime-plugin for OTA updates

Step 2: Configure Zephyr Dependencies

To enable Zephyr Cloud integration, add the zephyr:dependencies field to your package.json. Use the same key as in mfConfig.remotes:

// HostApp/package.json
{
  "name": "hostApp",
  "version": "1.0.0",
  "dependencies": {
    "react": "19.1.0",
    "react-native": "0.80.0"
  },
  "zephyr:dependencies": {
    "miniApp": "zephyr:miniApp@yourEnvironment-${target}"
  }
}
Environment Configuration
  • miniApp: The key of the remote in mfConfig.remotes. When bundle-mf-host or bundle-mf-remote runs, Zephyr replaces that remote's local URL with the resolved one
  • zephyr:miniApp@yourEnvironment-${target}: References the mini-app from a Zephyr environment. Zephyr replaces ${target} with the platform being bundled, so iOS builds load yourEnvironment-ios and Android builds load yourEnvironment-android
  • Replace yourEnvironment with your actual environment name prefix (e.g., staging, production)

For more information about managing dependencies, see Remote Dependencies.

Step 3: Publish the Host Application

Run the host publication command when you need to upload a host version. Keep the bundle output under dist/<platform> so Zephyr can discover the artifacts:

npx react-native bundle-mf-host --platform ios --dev false --entry-file index.js --bundle-output dist/ios/host.bundle

Verify the first host version in the dashboard just as you did for the mini application. For RNEF projects, use the required plugin and commands in the Metro bundler guide.

A release build bundles the host's JavaScript into the app binary. To embed the Zephyr-resolved remote URLs in it, configure the native bundle step to run bundle-mf-host, as described in Release builds.

Step 4: Load Mini Application in Your Code

Now you can use the mini application in your host app:

// HostApp/src/App.tsx
import React, { Suspense } from 'react';
import { View, Text, StyleSheet, ActivityIndicator } from 'react-native';

// Import the mini application component
const MiniAppComponent = React.lazy(() => import('miniApp/example'));

export default function App() {
  return (
    <View style={styles.container}>
      <Text style={styles.title}>Host Application</Text>

      <Suspense fallback={<ActivityIndicator size="large" color="#0000ff" />}>
        <MiniAppComponent />
      </Suspense>
    </View>
  );
}

const styles = StyleSheet.create({
  container: {
    flex: 1,
    padding: 20,
    justifyContent: 'center',
    alignItems: 'center',
  },
  title: {
    fontSize: 24,
    fontWeight: 'bold',
    marginBottom: 20,
  },
});
Tip

Always wrap lazy-loaded components with Suspense to handle loading states gracefully.

Running Your Application

Once both host and mini applications are configured:

Step 1: Start the Metro Bundler

In your host application directory:

cd HostApp
npx react-native start

Step 2: Run on iOS

Open a new terminal and run:

npx react-native run-ios

Step 3: Run on Android

Open a new terminal and run:

npx react-native run-android
Info

During development, the host loads mini-applications from the URLs specified in your Metro configuration. bundle-mf-host and bundle-mf-remote replace those URLs with the ones Zephyr resolves for the platform being bundled. start and debug run-ios / run-android builds do not publish an application version; run bundle-mf-remote or bundle-mf-host explicitly to build and upload one, or configure your release builds to run bundle-mf-host.

Best Practices

Shared Dependencies

Carefully manage shared dependencies to avoid version conflicts:

shared: {
  react: {
    singleton: true,  // Critical - only one React instance
    eager: true,      // Load immediately in host
    requiredVersion: '19.1.0',
    version: '19.1.0',
  },
  'react-native': {
    singleton: true,  // Critical - only one RN instance
    eager: true,
    requiredVersion: '0.80.0',
    version: '0.80.0',
  },
  // Be selective with other shared dependencies
  '@react-navigation/native': {
    singleton: true,
    eager: false,
    requiredVersion: '^6.0.0',
  },
}

Error Handling

Implement proper error boundaries for mini-applications:

import React, { Component, ReactNode } from 'react';
import { View, Text, StyleSheet } from 'react-native';

interface Props {
  children: ReactNode;
  fallback?: ReactNode;
}

interface State {
  hasError: boolean;
}

class MiniAppErrorBoundary extends Component<Props, State> {
  constructor(props: Props) {
    super(props);
    this.state = { hasError: false };
  }

  static getDerivedStateFromError(): State {
    return { hasError: true };
  }

  render() {
    if (this.state.hasError) {
      return (
        this.props.fallback || (
          <View style={styles.errorContainer}>
            <Text style={styles.errorText}>
              Failed to load mini application
            </Text>
          </View>
        )
      );
    }

    return this.props.children;
  }
}

const styles = StyleSheet.create({
  errorContainer: {
    padding: 20,
    backgroundColor: '#ffebee',
    borderRadius: 8,
  },
  errorText: {
    color: '#c62828',
    fontSize: 16,
  },
});

export default MiniAppErrorBoundary;

Platform-Specific Code

Handle platform differences in your mini-applications:

import { Platform } from 'react-native';

const styles = StyleSheet.create({
  container: {
    padding: Platform.select({
      ios: 20,
      android: 16,
    }),
  },
});

Troubleshooting

Mini Application Not Loading

If your mini application fails to load:

  1. Verify the remote URL in metro.config.js
  2. Check that the mini application was bundled successfully
  3. Ensure the mini application is deployed to Zephyr Cloud
  4. Verify network connectivity and CORS settings

Version Conflicts

If you encounter dependency version conflicts:

  1. Ensure shared dependencies have matching version ranges
  2. Use singleton: true for critical dependencies like React
  3. Check the Metro bundler logs for specific version mismatches

Build Failures

Common build issues and solutions:

  • Module not found: Verify the exposed path in the mini app's metro.config.js
  • Bundle size too large: Review shared dependencies and optimize imports
  • Cache issues: Clear Metro cache with npx react-native start --reset-cache

Next Steps

Now that you have Module Federation working with Metro, explore these advanced topics: