Skip to content

Commit 4909c8c

Browse files
EsemesekEsemesek
authored
chore: update documentation (#89)
1 parent 4a054f2 commit 4909c8c

File tree

3 files changed

+298
-35
lines changed

3 files changed

+298
-35
lines changed

‎CONTRIBUTING.md‎

Lines changed: 118 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,118 @@
1+
# Contributing
2+
3+
## Getting Started
4+
5+
### Prerequisites
6+
7+
- Node.js version 22 (as specified in `.nvmrc`)
8+
- Corepack
9+
10+
In case Corepack is not available, you can install it manually:
11+
12+
```bash
13+
npm install -g corepack
14+
```
15+
16+
### Setup Steps
17+
18+
1. Clone the repository with submodules:
19+
20+
```bash
21+
git clone [email protected]:module-federation/metro.git mf-metro
22+
```
23+
24+
2. Navigate to the project directory:
25+
26+
```bash
27+
cd mf-metro
28+
```
29+
30+
3. Enable Corepack and install dependencies in the monorepo:
31+
32+
```bash
33+
corepack enable && corepack install && yarn install
34+
```
35+
36+
## Development
37+
38+
Run the development servers for both showcase apps:
39+
40+
```bash
41+
yarn dev
42+
```
43+
44+
> **Note:** You can freely make changes to both the `@module-federation/metro` package (`packages/core`) and the the dev server will automatically restart when changes are detected - there's no need to manually build either package.
45+
46+
## Code Quality
47+
48+
### Linting
49+
50+
The project uses [Biome](https://biomejs.dev/) for linting and formatting. To check and fix code style issues:
51+
52+
```bash
53+
# Check and automatically fix linting issues
54+
pnpm lint
55+
56+
# Check linting issues without fixing (used in CI)
57+
pnpm lint:ci
58+
```
59+
60+
### Type Checking
61+
62+
To run TypeScript type checking across all packages:
63+
64+
```bash
65+
pnpm typecheck
66+
```
67+
68+
### Building
69+
70+
To build all packages:
71+
72+
```bash
73+
pnpm build
74+
```
75+
76+
## Running Examples
77+
78+
This repository includes several example applications to help you get started:
79+
80+
- **[example-host](./apps/example-host)** - Basic host application that consumes remote modules
81+
- **[example-mini](./apps/example-mini)** - Basic mini application that exposes modules
82+
- **[example-nested-mini](./apps/example-nested-mini)** - Mini application with nested module dependencies
83+
- **[showcase-host](./apps/showcase-host)** - Showcase host application with better UI
84+
- **[showcase-mini](./apps/showcase-mini)** - Showcase mini application with better UI
85+
86+
### Start Metro Servers
87+
88+
```shell
89+
# Run the basic example Metro servers
90+
pnpm dev:example
91+
92+
# Run the showcase example Metro servers
93+
pnpm dev
94+
```
95+
96+
### Build and Run on Devices
97+
98+
After starting the Metro servers, you can build and run the host apps on iOS and Android:
99+
100+
**For iOS:**
101+
```shell
102+
# Basic example
103+
pnpm --filter example-host ios
104+
105+
# Showcase example
106+
pnpm --filter showcase-host ios
107+
```
108+
109+
**For Android:**
110+
```shell
111+
# Basic example
112+
pnpm --filter example-host android
113+
114+
# Showcase example
115+
pnpm --filter showcase-host android
116+
```
117+
118+
> **Note**: Make sure you have the appropriate development environment set up for [iOS](https://reactnative.dev/docs/set-up-your-environment?platform=ios) and [Android](https://reactnative.dev/docs/set-up-your-environment?platform=android) development.

‎README.md‎

Lines changed: 37 additions & 35 deletions
Original file line numberDiff line numberDiff line change
@@ -1,56 +1,58 @@
1-
# Module Federation for Metro Bundler
1+
# Metro Module Federation
2+
3+
## About
4+
5+
This monorepo contains all the tools you'll need to adapt your React Native apps and start using Module Federation with Metro bundler.
6+
7+
### Packages in this repo:
8+
- `@module-federation/metro` - Core integration with Metro to enable Module Federation
9+
- `@module-federation/metro-plugin-rnc-cli` - React Native CLI integration
10+
- `@module-federation/metro-plugin-rnef` - React Native Enterprise Framework integration
11+
12+
> **Note**: Module Federation support for Metro bundler is still experimental and may lack some functionality or certain integrations.
213
314
## Getting Started
415

5-
### Prerequisites
16+
For detailed setup instructions and configuration options, see the [Metro Module Federation Core Package README](./packages/core/README.md).
17+
18+
## Usage
619

7-
- Node.js version 22 (as specified in `.nvmrc`)
8-
- Corepack
20+
The configuration follows the standard [Module Federation configuration format](https://module-federation.io/configure/). For detailed information about Module Federation concepts, configuration options, and usage patterns, please refer to the official [Module Federation documentation](https://module-federation.io/).
921

10-
In case Corepack is not available, you can install it manually:
22+
## Examples
1123

12-
```bash
13-
npm install -g corepack
14-
```
24+
This repository includes several example applications to help you get started:
1525

16-
### Setup Steps
26+
- **[example-host](./apps/example-host)** - Basic host application that consumes remote modules
27+
- **[example-mini](./apps/example-mini)** - Basic mini application that exposes modules
28+
- **[example-nested-mini](./apps/example-nested-mini)** - Mini application with nested module dependencies
29+
- **[showcase-host](./apps/showcase-host)** - Showcase host application
30+
- **[showcase-mini](./apps/showcase-mini)** - Showcase mini application
1731

18-
1. Clone the repository with submodules:
32+
For instructions on how to run these examples, see [Running Examples](./CONTRIBUTING.md#running-examples) in our Contributing Guide.
1933

20-
```bash
21-
git clone --recurse-submodules -j8 [email protected]:module-federation/metro.git mf-metro
22-
```
34+
### CLI Commands
2335

24-
2. Navigate to the project directory:
36+
For detailed information about available CLI commands see the [React Native CLI Plugin README](./packages/plugin-rnc-cli/README.md).
2537

26-
```bash
27-
cd mf-metro
28-
```
38+
### React Native Enterprise Framework (RNEF) Integration
2939

30-
3. Enable Corepack and install dependencies in the monorepo:
40+
For detailed information about RNEF integration and configuration, see the [RNEF Plugin README](./packages/plugin-rnef/README.md).
3141

32-
```bash
33-
corepack enable && corepack install && yarn install
34-
```
3542

36-
4. Navigate to the Metro submodule:
43+
## Contributing
3744

38-
```bash
39-
cd external/metro
40-
```
45+
We welcome contributions! Please see our [Contributing Guide](./CONTRIBUTING.md) for details on how to set up the development environment and run examples.
4146

42-
5. Set the correct Yarn version for Metro and install dependencies:
47+
## License
4348

44-
```bash
45-
yarn set version 1.22.22 && yarn install
46-
```
49+
This project is licensed under the MIT License - see the [LICENSE](./LICENSE) file for details.
4750

48-
## Development
51+
## Support
4952

50-
Run the development servers for both showcase apps:
53+
- 💬 [Discord Community](https://discord.gg/n69NnT3ACV)
54+
- 🐛 [GitHub Issues](https://github.com/module-federation/metro/issues)
5155

52-
```bash
53-
yarn dev
54-
```
56+
---
5557

56-
> **Note:** You can freely make changes to both the `@module-federation/metro` package (`packages/core`) and the the dev server will automatically restart when changes are detected - there's no need to manually build either package.
58+
Built with ❤️ by [Callstack](https://callstack.com) and [Zephyr Cloud](https://zephyr-cloud.io/).

‎packages/core/README.md‎

Lines changed: 143 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,143 @@
1+
# `@module-federation/metro`
2+
3+
## Getting started
4+
5+
### Installation
6+
7+
Use your favorite package manager to install these required packages to your React Native project.
8+
9+
```shell
10+
# Using pnpm
11+
pnpm add @module-federation/metro
12+
13+
# If your project is using React Native CLI
14+
pnpm add @module-federation/metro-plugin-rnc-cli
15+
16+
# If your project is using RNEF
17+
pnpm add @module-federation/metro-plugin-rnef
18+
```
19+
20+
### Configuration
21+
22+
Wrap Metro configuration with `withModuleFederation` function that enables module federation in your project.
23+
You should be wrapping all the federated modules' Metro configuration in this hook: host application and mini applications.
24+
25+
```javascript
26+
const { withModuleFederation } = require('@module-federation/metro');
27+
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
28+
29+
const config = {};
30+
31+
module.exports = withModuleFederation(
32+
mergeConfig(getDefaultConfig(__dirname), config),
33+
{
34+
// Module Federation configuration follows the same format as documented at:
35+
// https://module-federation.io/configure/index.html
36+
// Note: Some features might not be available in React Native environment
37+
name: 'YourAppName',
38+
remotes: {
39+
// Define remote applications (for host apps)
40+
// remoteName: 'remoteName@http://localhost:8082/mf-manifest.json',
41+
},
42+
exposes: {
43+
// Expose modules (for remote apps)
44+
// './Component': './src/Component.tsx',
45+
},
46+
shared: {
47+
// Host applications should set eager: true for all the shared dependencies
48+
react: {
49+
singleton: true,
50+
eager: true,
51+
requiredVersion: '19.1.0',
52+
version: '19.1.0',
53+
},
54+
'react-native': {
55+
singleton: true,
56+
eager: true,
57+
requiredVersion: '0.80.0',
58+
version: '0.80.0',
59+
},
60+
},
61+
},
62+
{
63+
// These experimental flags have to be enabled in order to patch older packages
64+
// Can be omitted if your project is using supported React Native and Metro versions
65+
flags: {
66+
// Enable patching HMR Client from React Native
67+
unstable_patchHMRClient: true,
68+
// Enable patching React Native CLI
69+
unstable_patchInitializeCore: true,
70+
// Enable patching runtime require from Metro
71+
unstable_patchRuntimeRequire: true,
72+
},
73+
}
74+
);
75+
```
76+
77+
#### Additional Configuration for RNEF Users
78+
79+
If you're using React Native Enterprise Framework (RNEF), follow the additional configuration instructions in the [RNEF Plugin README](../plugin-rnef/README.md).
80+
81+
### App Async Boundary Setup
82+
83+
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.
84+
85+
```javascript
86+
import { withAsyncStartup } from '@module-federation/runtime';
87+
import { AppRegistry } from 'react-native';
88+
89+
// Create async boundary through withAsyncStartup helper
90+
// Pass the getter function for the app component
91+
// Optionally pass a getter function for the fallback component
92+
const WrappedApp = withAsyncStartup(
93+
() => require('./App'),
94+
() => require('./Fallback') // Optional fallback component
95+
);
96+
97+
AppRegistry.registerComponent('YourAppName', WrappedApp);
98+
```
99+
100+
The `withAsyncStartup` function:
101+
- Waits for Module Federation runtime initialization before rendering your app
102+
- Uses React Suspense to handle the async loading
103+
- Accepts an optional fallback component to show during initialization
104+
105+
## API Reference
106+
107+
### `withModuleFederation(metroConfig, federationConfig, options?)`
108+
109+
Wraps your Metro configuration to enable Module Federation.
110+
111+
#### Parameters
112+
113+
- `metroConfig` (MetroConfig) - Your existing Metro configuration
114+
- `federationConfig` (FederationConfig) - Module Federation configuration
115+
- `options` (Options) - Optional configuration for experimental features
116+
117+
#### FederationConfig
118+
119+
```typescript
120+
121+
export interface ModuleFederationConfig {
122+
name: string;
123+
filename?: string;
124+
remotes?: Record<string, string>;
125+
exposes?: Record<string, string>;
126+
shared?: Shared;
127+
shareStrategy?: 'loaded-first' | 'version-first';
128+
plugins?: string[];
129+
}
130+
```
131+
132+
#### SharedConfig
133+
134+
```typescript
135+
export interface SharedConfig {
136+
singleton: boolean;
137+
eager: boolean;
138+
version: string;
139+
requiredVersion: string;
140+
import?: false;
141+
}
142+
```
143+

0 commit comments

Comments
 (0)