React Native Shell + Host Architecture (Beta)
In the usual Metro Module Federation setup, the host app ships inside the store binary and loads remotes from Zephyr. The remotes can change over the air, but the host's own code cannot: changing it takes a new store release.
The Native Shell + Host architecture moves the host out of the binary. The binary contains only a Native Shell: native code plus a small JavaScript bundle that loads a Host from Zephyr and owns recovery controls. The Host composes the product UI from remotes. Because the shell follows its own Zephyr environment, that environment becomes the central point of control for every installed app: it decides which Host they load and which ZE_PUBLIC_* values the shell sees.
This page describes a recommended architecture that is in beta. It uses the same packages and APIs as React Native OTA Updates, including runtimeManifest from version 1.8.0. The recommended project layout and wiring may change as we collect feedback. The architecture also depends on @module-federation/metro 2.9 behavior with known issues.
Only the Native Shell is in the binary, so only the shell can link native code. The Host and remotes can use native modules only if the installed shell already contains them at the same version. New native modules, permissions, and React Native upgrades still need a store release of the shell.
Layers
The Host is a Module Federation remote of the shell that exposes its root component. It is published with bundle-mf-remote, like any other remote.
How Control Flows
- The shell binary is built with a default Host,
host@production-${target}, and withruntimeManifest: '@production-${target}', which points at the shell's own environment. - On launch, the shell's first remote request applies the shell environment's
zephyr-manifest.jsonstored by the previous launch. A remote override forhostin that manifest replaces the default Host; itsZE_PUBLIC_*values apply to the shell. - The shell loads the selected Host. Before the Host's code runs, the Zephyr runtime plugin applies the Host environment's
ZE_PUBLIC_*values and remote overrides. - The Host loads its remotes. Each remote gets the values of the environment it was loaded from.
- In the background, the shell fetches a fresh copy of its environment's manifest and stores it for the next launch.
Use the shell environment's host override for coarse decisions that affect every installed app: switching all users to a canary Host, pinning a known-good Host version, or rolling back. Use the Host's environment for day-to-day releases of the Host and its remotes.
Prerequisites
- The Metro bundler guide setup, including release builds that run
bundle-mf-host zephyr-metro-pluginandzephyr-native-cache1.8.0 or newer- React Native OTA Updates concepts: per-platform environments, environment values, and
runtimeManifest
Project Layout
Each app is its own package, so each has its own Zephyr application identity:
Install the native cache in the shell only:
Shared Dependencies
The shell provides every shared package eagerly. The Host and remotes take those packages from the shell with import: false and never bundle their own copy.
Follow these rules:
- Share
reactand every package with native code (an Android project or an iOS podspec) that the Host or a remote depends on, at the shell's exact version. - Share only what some Host or remote uses. With
@module-federation/metro2.9.0, a package the shell shares eagerly that no consumer declares, such aszephyr-native-cache, fails remote container initialization with_targetShared.get is not a function. - Fail the Host or remote build when it depends on a native package the shell doesn't provide, or on a different version of one. Its JavaScript would call native code that is missing from, or different in, the installed binary.
Deriving shared from the apps' package.json files keeps these rules in one place: read the shell's dependencies, keep react and the packages that ship native code, and throw from a consumer's Metro config when a native dependency is missing or mismatched.
This check runs at build time only. A Host published against a newer shell can still reach an older installed binary. Publish to environments that only shells with the same native dependencies follow, for example by giving each native release its own environment names.
Module Federation shares by exact specifier. If a dependency imports a package's internals by deep path, such as react-native/Libraries/..., share that path too, or the remote bundles a second copy.
The Native Shell
The shell declares the Host as its only remote. Its local URL serves development; Zephyr builds resolve the Host from the shell's zephyr.config.*:
Write ${target} selectors in plain quotes, not template literals. Zephyr replaces ${target} with ios or android when it resolves them.
Register the native cache before anything loads the Host, and put an error boundary around the whole shell:
The shell's UI loads the Host lazily and keeps the controls that must work even when the Host is broken:
Retry reloads the JavaScript context. That also applies a host override the shell fetched during the failed session, so fixing the shell environment in the dashboard recovers devices stuck on a broken Host.
Configure the shell's release build to run bundle-mf-host through the Zephyr command, so the binary contains the resolved default Host and the runtimeManifest URL.
The Host
The Host is a remote of the shell. It exposes its root component and declares its own remotes:
Wrap each remote in its own error boundary and Suspense fallback, so one failing remote does not take the Host down. Publish the Host with bundle-mf-remote:
The Host does not need zephyr-native-cache or its runtime plugin. The shell's runtime plugins register globally, so they also handle the Host's remotes.
Remotes
Remotes are ordinary Metro Module Federation remotes with import: false shared dependencies. Publish them before the Host, for each platform:
Build Modes
Gate Zephyr on an environment variable so local development needs no Zephyr login. Plain builds use the stock Module Federation RNEF plugin and the localhost remotes; Zephyr builds use withZephyr() and the Zephyr RNEF plugin:
Zephyr builds need Zephyr login and a Git repository with at least one commit; the branch and commit come from Git.
Environments
Create one environment per platform on every app: native-shell, host, and each remote. An environment serves one version, and each version is built for one platform, so a shared production environment would hand one platform's bundle to the other.
Publish in dependency order, so each build resolves the environments it depends on:
- The remotes, for each platform.
- The Host, for each platform.
- The shell's release build, for each platform, with
ZE_ENVset to its environment.
A shell build with runtimeManifest fails while the shell has no version in that platform's environment, because the selector cannot resolve. For the first build on each platform, build without runtimeManifest and publish it with ZE_ENV, then add runtimeManifest back and rebuild.
The first launch after installing has no stored shell manifest, so it loads the build-time default Host. Overrides on the shell environment apply from the next launch. The stored manifest survives app updates, so an updated binary that follows the same shell environment starts with the Host that environment last selected.
Diagnostics
Metro Module Federation records each loaded entry URL in __FEDERATION__.__NATIVE__[name].origin. Showing it in an internal screen tells you which Host and remote deployments a device actually loaded:
Known Issues
- Images in remotes.
@module-federation/metro2.9 resolves a remote'srequired image against the shell's dev server, andbundle-mf-remotedoes not emit assets. Inline small images, for example as data URIs, or load images from URLs. - Entry file names that appear in the dev-server URL.
@module-federation/metro2.9 rewrites the first occurrence of a remote'sfilename, without its extension, anywhere in a request URL. A Host withfilename: 'host.bundle'served fromhttp://localhost:8082/host.bundlemakes Metro rewrite part oflocalhostand crash in development. Choose afilenamethat does not occur earlier in the dev-server URL, or patch the rewrite to match only the/<entry>path segment. - Shared modules required during startup. In
@module-federation/metro2.9, a shared module required synchronously before its async load finishes receives an empty placeholder. This only affects shared packages other thanreactandreact-nativethat are required while the app starts. - Overrides repoint declared remotes only. An environment override cannot add a remote that the build did not declare.
- Store review. The Host and remotes are downloaded executable JavaScript. Keep them within the purpose and capabilities your store submission was reviewed for.