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.
- 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:
- Independent Development: Teams can develop mini-applications in isolation with their own release cycles
- Code Sharing: Efficient sharing of common dependencies and utilities across applications
- Runtime Loading: Dynamic loading of mini-applications without requiring app store updates
- Scalability: Easy addition of new features and micro-frontends as your application grows
- 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:
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:
Create a new React Native mini application:
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:
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:
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:
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:
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:
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:
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:dependenciesentry 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-pluginfor 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:
Environment Configuration
- miniApp: The key of the remote in
mfConfig.remotes. Whenbundle-mf-hostorbundle-mf-remoteruns, 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 loadyourEnvironment-iosand Android builds loadyourEnvironment-android- Replace
yourEnvironmentwith 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:
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:
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:
Step 2: Run on iOS
Open a new terminal and run:
Step 3: Run on Android
Open a new terminal and run:
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:
Error Handling
Implement proper error boundaries for mini-applications:
Platform-Specific Code
Handle platform differences in your mini-applications:
Troubleshooting
Mini Application Not Loading
If your mini application fails to load:
- Verify the remote URL in metro.config.js
- Check that the mini application was bundled successfully
- Ensure the mini application is deployed to Zephyr Cloud
- Verify network connectivity and CORS settings
Version Conflicts
If you encounter dependency version conflicts:
- Ensure shared dependencies have matching version ranges
- Use
singleton: truefor critical dependencies like React - 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:
- Explore our example repository for complete working examples
- Add React Native OTA Updates with
zephyr-native-cache - Review the OTA example repository for a full host/remotes setup
- Explore the Native Shell + Host architecture to control installed apps from one Zephyr environment
- Learn about Tags & Environments for managing different deployment stages
- Check out Remote Dependencies for advanced dependency configuration
- Review End-to-End Testing for testing federated applications
- Set up CI/CD pipelines for automated deployments with CI tokens
- Migrate existing personal-token or server-token deployments to CI tokens