# 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:
```shell
# 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.
```javascript
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.
```javascript
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:
```javascript
// 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:
```javascript
// 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:
```shell
# 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:
```shell
# 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)](https://github.com/callstack/react-native-enterprise-framework), add the Module Federation plugin to your `rnef.config.mjs`:
```javascript
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 configuration
- `federationConfig` (FederationConfig) - Module Federation configuration
- `options` (Options) - Optional configuration for experimental features
#### FederationConfig Interface
```typescript
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
```typescript
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](https://module-federation.io/configure/). For comprehensive information about Module Federation concepts, configuration options, and usage patterns, please refer to the official [Module Federation documentation](https://module-federation.io/).
For working examples and detailed implementation guides, check out the [Module Federation Metro repository](https://github.com/module-federation/metro) which includes several example applications demonstrating different usage patterns and integrations.
