Metro
Metro Module Federation brings the power of distributed architecture to React Native mobile development.
Overview
The Module Federation implementation for React Native uses a custom Metro bundler integration that enables:
- Micro-frontend architecture for React Native apps
- Code sharing between multiple React Native applications
- Independent deployment of application modules
- Runtime module loading for dynamic updates
Note: Module Federation support for Metro bundler is still experimental and may lack some functionality or certain integrations. Projects or libraries that rely on custom Metro configurations aren't supported yet and might not work.
Packages
The React Native Module Federation ecosystem consists of several packages:
@module-federation/metro - Core integration with Metro to enable Module Federation@module-federation/metro-plugin-rnc-cli - React Native CLI integration@module-federation/metro-plugin-rnef - React Native Enterprise Framework integration
Installation
Install the required packages to your React Native project using your preferred package manager:
# Core package (required)
pnpm add @module-federation/metro
# If your project is using React Native CLI
pnpm add @module-federation/metro-plugin-rnc-cli
# If your project is using React Native Enterprise Framework (RNEF)
pnpm add @module-federation/metro-plugin-rnef
Configuration
Wrap your Metro configuration with the withModuleFederation function to enable Module Federation. You should be wrapping all the federated modules' Metro configuration in this hook: host application and mini applications.
const { withModuleFederation } = require('@module-federation/metro');
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const config = {};
module.exports = withModuleFederation(
mergeConfig(getDefaultConfig(__dirname), config),
{
// Module Federation configuration follows the same format as documented at:
// https://module-federation.io/configure/index.html
// Note: Some features might not be available in React Native environment
name: 'YourAppName',
remotes: {
// Define remote applications (for host apps)
// remoteName: 'remoteName@http://localhost:8082/mf-manifest.json',
},
exposes: {
// Expose modules (for remote apps)
// './Component': './src/Component.tsx',
},
shared: {
// Host applications should set eager: true for all the shared dependencies
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',
},
},
},
{
// These experimental flags have to be enabled in order to patch older packages
// Can be omitted if your project is using supported React Native and Metro versions
flags: {
// Enable patching HMR Client from React Native
unstable_patchHMRClient: true,
// Enable patching React Native CLI
unstable_patchInitializeCore: true,
// Enable patching runtime require from Metro
unstable_patchRuntimeRequire: true,
},
}
);
App Async Boundary Setup
Wrap your main App component with withAsyncStartup to enable Module Federation runtime. This creates an async boundary that ensures the Module Federation runtime is properly initialized before your app component renders.
import { withAsyncStartup } from '@module-federation/runtime';
import { AppRegistry } from 'react-native';
// Create async boundary through withAsyncStartup helper
// Pass the getter function for the app component
// Optionally pass a getter function for the fallback component
const WrappedApp = withAsyncStartup(
() => require('./App'),
() => require('./Fallback') // Optional fallback component
);
AppRegistry.registerComponent('YourAppName', WrappedApp);
The withAsyncStartup function:
- Waits for Module Federation runtime initialization before rendering your app
- Uses React Suspense to handle the async loading
- Accepts an optional fallback component to show during initialization
Usage Patterns
Host Application
A host application consumes remote modules from other applications:
// metro.config.js for host app
module.exports = withModuleFederation(
mergeConfig(getDefaultConfig(__dirname), config),
{
name: 'HostApp',
remotes: {
'mini-app': 'miniApp@http://localhost:8082/mf-manifest.json',
'another-app': 'anotherApp@http://192.168.1.100:8083/mf-manifest.json',
},
shared: {
react: { singleton: true, eager: true },
'react-native': { singleton: true, eager: true },
},
}
);
Remote Application (Mini App)
A remote application exposes modules that can be consumed by host applications:
// metro.config.js for remote app
module.exports = withModuleFederation(
mergeConfig(getDefaultConfig(__dirname), config),
{
name: 'MiniApp',
exposes: {
'./Screen': './src/Screen.tsx',
'./Component': './src/Component.tsx',
},
shared: {
react: { singleton: true, eager: true },
'react-native': { singleton: true, eager: true },
},
}
);
CLI Commands
The React Native CLI integration provides additional commands for bundling federated applications:
Bundle Module Federation Host
Bundle a host application that consumes remote modules:
# Bundle for iOS
react-native bundle-mf-host --entry-file index.js --platform ios
# Bundle for Android
react-native bundle-mf-host --entry-file index.js --platform android
Bundle Module Federation Remote
Bundle a remote application (mini app) that exposes modules:
# Bundle for iOS
react-native bundle-mf-remote --platform ios
# Bundle for Android
react-native bundle-mf-remote --platform android
Both commands support all the same options as the standard react-native bundle command.
Note: These commands are provided by the @module-federation/metro-plugin-rnc-cli package.
React Native Enterprise Framework (RNEF) Integration
For projects using React Native Enterprise Framework (RNEF), add the Module Federation plugin to your rnef.config.mjs:
import { pluginMetroModuleFederation } from '@module-federation/metro-plugin-rnef';
import { platformAndroid } from '@rnef/platform-android';
import { platformIOS } from '@rnef/platform-ios';
import { pluginMetro } from '@rnef/plugin-metro';
/** @type {import('@rnef/config').Config} */
export default {
bundler: pluginMetro(),
platforms: {
ios: platformIOS(),
android: platformAndroid(),
},
plugins: [pluginMetroModuleFederation()],
};
API Reference
withModuleFederation(metroConfig, federationConfig, options?)
Wraps your Metro configuration to enable Module Federation.
Parameters
metroConfig (MetroConfig) - Your existing Metro configurationfederationConfig (FederationConfig) - Module Federation configurationoptions (Options) - Optional configuration for experimental features
FederationConfig Interface
export interface ModuleFederationConfig {
name: string;
filename?: string;
remotes?: Record<string, string>;
exposes?: Record<string, string>;
shared?: Shared;
shareStrategy?: 'loaded-first' | 'version-first';
plugins?: string[];
}
SharedConfig Interface
export interface SharedConfig {
singleton: boolean;
eager: boolean;
version: string;
requiredVersion: string;
import?: false;
}
Examples and Best Practices
The configuration follows the standard Module Federation configuration format. For comprehensive information about Module Federation concepts, configuration options, and usage patterns, please refer to the official Module Federation documentation.
For working examples and detailed implementation guides, check out the Module Federation Metro repository which includes several example applications demonstrating different usage patterns and integrations.
