DEV Community: Warren de Leon

Fallback for federated remotes: the copy in the binary and the net in the session

Warren de Leon — Mon, 19 Oct 2026 00:03:59 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 15 ended its break-it section on its own limit: "None of this gives the binary anywhere else to load from: a dead tab is honest, and it is not a working app." This post gives the binary somewhere else. Every release build now carries a copy of each remote, and the app runs from those copies when the content delivery network (CDN) cannot be reached, or when one remote fails to load while the other keeps loading from it.

Post 1 said who builds that: "Module Federation gives you none of the offline story by itself: shipping a copy of each remote inside the binary, so the reviewed app works on its own with no network, is an architecture you build." It also set the requirement for a remote that will not load: "the app has to degrade to something safe instead of showing a blank screen." Post 15's build meets the requirement for a remote that will not load, and stops there. With the CDN out of reach it launches unresolved, with an error state in either tab. When one remote fails, its tab shows the error state, and Try again never brings the tab back.

The first half builds the copy: a build step that stages it, a phase on each platform that puts it in the binary, and a new launch mode, bundled, that runs every remote from it. The second half builds two nets for a CDN launch. One catches a manifest the CDN cannot serve and drops that one remote to its copy; the other sits around each tab and catches a load that fails later. A Try again that actually retries comes with the second net.

One rule shapes the copy: it is the version already known to run on this binary, frozen on the day the binary was built. It is the guaranteed minimum: new versions still reach installed apps through the CDN, and the host uses the copy only when the CDN cannot deliver a version that loads.

Start from post 15's finished state, the tag post-15-cdn-flip; this post finishes at post-16-fallbacks. As before, you type the configuration changes and the smaller edits, and copy the rest from the end tag: the build tool, the host's code and tests, the native files and one design-system test.

📊 Diagram: view it on warrendeleon.com

The launch decides the mode once, before anything federated loads. Using the CDN's versions means a usable map arrived and its versions registered; when they cannot be used, the launch registers the copies instead. It ends unresolved only when that fails too. The two nets act inside a CDN launch, one remote at a time.

Put a copy of each remote in the binary

A copy is chosen by the same map that picks versions from the CDN. The version a binary carries is the one its own app version's map names, because that is the version known to run on that binary: for the 2.0.0 build here, list 1.2.0 and party 1.0.0.

The copy holds that version's signed bundles and its manifest, byte for byte as the CDN serves them. The bytes stay as they are because every bundle is still verified against the signing key when it loads, and a change to its code fails the check.

tools/build-cdn.mjs already builds every version into cdn-root/, and it now stages the copies as well. Fetch the end tag once, since every copy command in this post takes its files from it, and take the tool first:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-16-fallbacks /tmp/pokedex-ref-16

cp /tmp/pokedex-ref-16/tools/build-cdn.mjs tools/

The new stage runs after the CDN tree is built. For each platform it takes every version the map names and copies its bundles and manifest into embed-root/<platform>/<remote>/<version>/:

for (const [remote, version] of Object.entries(embeddedVersions)) {
  const published = join(cdnDir, remote, version);
  const embedded = join(embedDir, remote, version);
  mkdirSync(embedded, { recursive: true });
  // Every script of the version sits at the top of its directory with its manifest, and the copy
  // is all of them, byte for byte: the container, its chunks, index.bundle, which the manifest
  // names among the shared modules' assets, and mf-manifest.json, which the federation runtime
  // reads from the disk the way it reads it from the CDN. The assets/ folder beside them holds
  // images the host's shared copies of those libraries already carry.
  for (const file of readdirSync(published)) {
    if (file.endsWith('.bundle') || file === 'mf-manifest.json') {
      copyFileSync(join(published, file), join(embedded, file));
    }
  }
  bundledVersions[platform][remote] = version;

The copies keep the <remote>/<version>/ directories instead of sharing one folder, because two remotes can ship vendor chunks with the same file name. In one folder, the second would overwrite the first.

The build tool also records the copied versions in apps/host/src/shell/embedded-versions.ts, a generated file the host compiles in, so the host knows which copies it carries before it reads anything from the disk.

embed-root/ is build output, like cdn-root/, so add it to .gitignore:

# The copies build-cdn stages for the native embed phases.
embed-root/

Run the key generator first, then the tool for both platforms. The generator keeps any keys the checkout already has, and creates them on a fresh checkout of the tag, which has none because they never enter Git. After the CDN tree, the tool reports the copies and the generated file:

node tools/gen-signing-keys.mjs && node tools/build-cdn.mjs

embedded  -> embed-root/ios/listApp/1.2.0
embedded  -> embed-root/ios/partyApp/1.0.0
embedded  -> embed-root/android/listApp/1.2.0
embedded  -> embed-root/android/partyApp/1.0.0
wrote     -> apps/host/src/shell/embedded-versions.ts

The generated file records the version of each copy, per platform:

export const BUNDLED_VERSIONS: Record<string, Record<string, string>> = {
  ios: { listApp: '1.2.0', partyApp: '1.0.0' },
  android: { listApp: '1.2.0', partyApp: '1.0.0' },
};

The build tool stages the copy for the app version in MF_APP_VERSION, or for the newest app version with a map when that is unset, so a build for another app version runs the tool with the same variable first.

iOS: the last build phase

On iOS the copy goes inside the .app, next to main.jsbundle. A script does the copying, and a Run Script phase at the end of the Host target runs it. Copy the script from the end tag:

mkdir -p apps/host/scripts && cp /tmp/pokedex-ref-16/apps/host/scripts/embed-remotes-ios.sh apps/host/scripts/

#!/usr/bin/env bash
# --- The copy in the binary, iOS's half. The last Run Script phase of the Host target copies each
# remote's embedded version from embed-root/ios into the app, at cdn/ios/<remote>/<version>/ next
# to main.jsbundle, where the host reads it through absolute file:// URLs: the signed bundles and
# the version's mf-manifest.json.
#
# The <remote>/<version>/ directories are kept rather than flattened: two remotes can ship vendor
# chunks with the same file name, and a flat copy would let one overwrite the other.
#
# It runs in every configuration. A Debug build loads the host's own bundle over http, so it cannot
# read the copy, and there the copy only costs the time it takes. Its remotes come from the dev
# servers when no CDN is configured, or from the CDN when one is.
#
# With embed-root missing it removes any copy an earlier build left behind, prints a warning and
# exits 0, and the build succeeds with nothing embedded. That is the trap: run
# `node tools/build-cdn.mjs` before a release build. ---
set -euo pipefail

REPO_DIR=$(cd "$(dirname "${BASH_SOURCE[0]}")/../../.." && pwd)
SOURCE="$REPO_DIR/embed-root/ios"
: "${CONFIGURATION_BUILD_DIR:?run this from an Xcode build phase}"
: "${UNLOCALIZED_RESOURCES_FOLDER_PATH:?run this from an Xcode build phase}"
DEST="$CONFIGURATION_BUILD_DIR/$UNLOCALIZED_RESOURCES_FOLDER_PATH/cdn/ios"

if [ ! -d "$SOURCE" ]; then
  rm -rf "$DEST"
  rmdir "$(dirname "$DEST")" 2>/dev/null || true
  echo "warning: $SOURCE does not exist, so no remotes are embedded. Run 'node tools/build-cdn.mjs' before a release build."
  exit 0
fi

mkdir -p "$DEST"
# --delete keeps the app to exactly what embed-root holds, so a version an earlier build embedded
# does not linger. The bytes are copied as they are: each bundle is signed over them.
rsync -a --delete --include='*/' --include='*.bundle' --include='mf-manifest.json' --exclude='*' "$SOURCE/" "$DEST/"
echo "embedded $(find "$DEST" -name '*.bundle' | wc -l | tr -d ' ') remote bundles and $(find "$DEST" -name 'mf-manifest.json' | wc -l | tr -d ' ') manifests into $DEST"

The phase is one change to the project file. In Xcode it is a new Run Script phase on the Host target, named "Embed federated remotes (offline fallback)", running "$SRCROOT/../scripts/embed-remotes-ios.sh", placed after every other phase, with "Based on dependency analysis" unchecked. It goes last so that the .app it writes into is already assembled. With the box unchecked it runs on every build, which a phase that declares no outputs does anyway: Xcode skips a script phase only when it has outputs to check. Declaring the copied files under the .app's cdn/ios as outputs, with embed-root/'s files as inputs, is the alternative. The end tag's project file carries the phase with the box unchecked, so copying it makes the same change:

cp /tmp/pokedex-ref-16/apps/host/ios/Host.xcodeproj/project.pbxproj apps/host/ios/Host.xcodeproj/

Android: a Gradle task and a native module

On Android the copy goes into the assets of the APK, the Android package an app is installed from. At the end of apps/host/android/app/build.gradle, after post 15's changes, add:

// --- The copy in the binary, Android's half. build-cdn stages each remote's embedded version under
// embed-root/android, the signed bundles and the version's mf-manifest.json, and this task mirrors
// that tree into the APK's assets at cdn/android, where EmbeddedRemotesModule copies it out at
// launch. Sync rather than Copy, so a file an earlier build embedded and this one does not is
// removed instead of shipped.
//
// With embed-root missing, this task embeds nothing, warnIfNothingToEmbed prints a warning, and the
// build still succeeds. That is the trap: a successful release build that carries no copies. Run
// build-cdn before a release build. ---
def embedSource = file("$rootDir/../../../embed-root/android")
def embeddedAssetsDir = layout.buildDirectory.dir("generated/embedded-remotes").get().asFile

def embedRemotes = tasks.register('embedRemotes', Sync) {
    from(embedSource) { include '**/*.bundle', '**/mf-manifest.json' }
    into(file("$embeddedAssetsDir/cdn/android"))
}

// --- A Sync with no source skips its actions, so a warning inside it would never print. Gradle
// still clears what the task embedded before when its source goes, so no stale copy ships. This
// task has no inputs or outputs, so it runs on every build, and it prints the warning when
// embed-root/android is missing. ---
def warnIfNothingToEmbed = tasks.register('warnIfNothingToEmbed') {
    doLast {
        if (!embedSource.exists()) {
            logger.warn("warning: ${embedSource} does not exist, so no remotes are embedded. Run 'node tools/build-cdn.mjs' before a release build.")
        }
    }
}

android {
    sourceSets {
        main {
            assets.srcDirs += embeddedAssetsDir
        }
    }
}

tasks.named('preBuild').configure { dependsOn embedRemotes, warnIfNothingToEmbed }

An asset is not a file on disk, and Re.Pack reaches a copy's <remote>/<version>/ directory only through a real file path. So a small TurboModule copies assets/cdn out to the app's files directory and resolves with the directory it used. Its spec is short enough to read whole:

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

// --- Android's half of the copy in the binary. A Gradle task packs each remote's embedded version
// into the APK's assets, and assets are not files on disk: Re.Pack's file:// loader needs a real
// path. prepare() copies them out to the app's files directory once per installed build, keeping
// the <remote>/<version>/ layout, and resolves with the directory the host builds file:// URLs
// against.
//
// There is no iOS implementation, because iOS reads the copies straight from the .app. That is why
// this uses TurboModuleRegistry.get, which returns null where the module does not exist, rather
// than getEnforcing, which would throw on iOS the moment this file loads. ---
export interface Spec extends TurboModule {
  /** Copy the embedded remotes out, once per installed build, and return the directory. */
  prepare(appVersion: string): Promise<string>;
}

export default TurboModuleRegistry.get<Spec>('EmbeddedRemotesModule');

The Kotlin side copies the tree once per install. A marker file holds the app version and the time the APK was installed or updated, so a relaunch reuses the extracted tree, and any new install replaces it, including a rebuilt APK that kept its version number. It copies the bytes as they are, since each bundle's signature covers them. Take the module, its spec and the updated HostNativePackage, which registers it next to post 13's navigation module, from the end tag:

cp /tmp/pokedex-ref-16/apps/host/specs/NativeEmbeddedRemotesModule.ts apps/host/specs/
cp /tmp/pokedex-ref-16/apps/host/android/app/src/main/java/com/host/{EmbeddedRemotesModule,HostNativePackage}.kt apps/host/android/app/src/main/java/com/host/

	iOS	Android
Where the copy goes	the `.app`, at `cdn/ios/<remote>/<version>/`	the APK's assets, at `cdn/android/<remote>/<version>/`, copied out to the files directory at launch
What puts it there	the last Run Script phase, `embed-remotes-ios.sh`	the `embedRemotes` Sync task, before `preBuild`
How the host finds it	the directory of `main.jsbundle`, read from React Native's `SourceCode` module	the directory `EmbeddedRemotesModule.prepare()` resolves with
Without `embed-root/`	a warning, a successful build, no copy	a warning, a successful build, no copy

Load a copy from the disk

The host changes in five files and their tests. Take them from the end tag. mf-modules.d.ts goes, because nothing loads a remote with import() any more (the Try again section says why), and the design system gains a contrast check for the banner's new colour:

cp /tmp/pokedex-ref-16/apps/host/src/shell/{remoteLocator,scriptManager,federationErrors}.ts /tmp/pokedex-ref-16/apps/host/src/shell/FederationBanner.tsx apps/host/src/shell/
cp /tmp/pokedex-ref-16/apps/host/App.tsx /tmp/pokedex-ref-16/apps/host/jest.config.js apps/host/
cp /tmp/pokedex-ref-16/apps/host/__mocks__/{module-federation-runtime,partyApp-partySlice}.js apps/host/__mocks__/
cp /tmp/pokedex-ref-16/apps/host/__tests__/{remoteLocator,scriptManager}.test.ts /tmp/pokedex-ref-16/apps/host/__tests__/{App,RemoteBoundary,FederationBanner}.test.tsx apps/host/__tests__/
cp /tmp/pokedex-ref-16/packages/ui/src/tokens/__tests__/contrast.accessibility.ts packages/ui/src/tokens/__tests__/
rm apps/host/mf-modules.d.ts

The host first has to know where the copies are on the device. On iOS the answer comes from React Native's own SourceCode module: a release build loads file:///…/Host.app/main.jsbundle, and the directory above that file is the .app. A development build loads its bundle from the dev server over http, so there is no directory to derive and no copy to use. On iOS, everything that runs from a copy needs a release build. On Android the directory is whatever prepare() resolved with:

const sourceCode = NativeModules.SourceCode as
  | { scriptURL?: string; getConstants?: () => { scriptURL?: string } }
  | undefined;
const SCRIPT_URL = sourceCode?.scriptURL ?? sourceCode?.getConstants?.().scriptURL;
const APP_PATH = SCRIPT_URL?.startsWith('file://')
  ? SCRIPT_URL.replace(/^file:\/\//, '').replace(/\/[^/]+$/, '')
  : undefined;

let embeddedRoot: string | undefined = Platform.OS === 'ios' ? APP_PATH : undefined;

Every script of a remote still goes through post 15's resolver. It gains one branch: a remote that runs from its copy, in a launch that could not use the CDN's versions, or after that one remote failed to load from the CDN, resolves to a file inside its copy:

return {
  kind: 'locate',
  locator: {
    url: `file://${input.embeddedRoot}/cdn/${input.platform}/${remoteName}/${version}/${filename}`,
    cache: true,
    absolute: true,
    verifyScriptSignature: input.verify,
  },
};

absolute: true is the detail that is easy to miss. Without it, Re.Pack keeps only the script's file name and looks for it at the top level of the app: iOS asks the app bundle's resources through URLForResource:withExtension:, and Android opens an asset of that name. Neither reaches a <remote>/<version>/ directory. With it, Re.Pack reads the file at the path as given.

Verification stays on. Re.Pack's file loader on both platforms runs the same signature check as its download path, before the code runs, on every load. That makes the copy stricter than a cached download, which post 15 noted is run from the disk without a second check. It is also why the copy is never rewritten on its way into the app: change one byte of an installed copy's code and the tab refuses it, failing the same hash check as a tampered download. On iOS the file loader reports the error's full description, so the reason arrives behind the system's generic prefix:

[Error: The operation couldn’t be completed. The bundle verification failed because the bundle hash is invalid.]

On Android the message reads as it does for a tampered download, with no prefix.

The manifest needs no special handling. The copy carries mf-manifest.json beside its bundles, and the federation runtime reads it from a file:// URL the way it reads one from the CDN, because React Native's fetch opens local files: through its file request handler on iOS, and on Android through the blob module's handler, which takes any URL that is not http or https when the response type is blob, the type React Native's fetch asks for.

Bundled mode: the day the CDN is unreachable

The launch now prepares the copies alongside the probe, since neither needs the other, and a launch with no usable map runs from them instead of giving up:

const [versions] = await Promise.all([
  CDN_CONFIGURED ? fetchVersionMap() : Promise.resolve(null),
  prepareEmbeddedCopies(),
]);
if (!versions) {
  return runFromCopies(CDN_CONFIGURED ? 'no usable version map' : 'no CDN configured');
}

// --- The launch that could not use the CDN: no usable map, no CDN configured, or a registration
// that failed. With copies in the binary it runs from them, every remote registered at its copy's
// manifest, which the runtime reads from the disk. With none, or when registering them fails too,
// there is nothing to run. ---
function runFromCopies(reason: string): FederationStatus {
  const embedded = REMOTE_NAMES.filter(hasEmbeddedCopy);
  if (embedded.length === 0) {
    setStatus({ mode: 'unresolved', source: reason, versions: {}, embedded: [] });
    return status;
  }
  const versions = Object.fromEntries(embedded.map(name => [name, bundledVersions[name]]));
  setStatus({ mode: 'bundled', source: 'the copy in the binary', versions, embedded });
  try {
    registerRemotes(
      embedded.map(name => ({ name, entry: embeddedManifestUrlFor(name) })),
      { force: true },
    );
  } catch (error) {
    console.warn('[federation] the copies could not be registered', error);
    setStatus({ mode: 'unresolved', source: 'remotes could not be registered', versions: {}, embedded: [] });
  }
  return status;
}

Registering each remote at its copy's manifest, with post 15's force, sends the runtime to the disk for everything about that remote. From there nothing else is special: the runtime fetches the manifest, the resolver sends every script to the copy, and each one is verified as it loads. unresolved remains for a launch whose binary records no copy with a directory to load from, or where registering the copies fails.

Try it by taking the CDN away. Start the server as post 15 did, then make the Release build:

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release )

The banner reads cdn · listApp 1.2.0 · partyApp 1.0.0. Stop the server and check that the map is gone:

curl -s -o /dev/null http://localhost:8000/ios/maps/2.0.0/version-map.json; echo $?

7 means curl could not connect. Close the app and open it again. The probe fails within its 1.5 seconds, the banner turns purple and reads bundled · listApp 1.2.0 · partyApp 1.0.0, and both tabs open from the copies, with nothing asked of the network except PokéAPI for the Pokémon and GitHub for their artwork.

The copy is frozen at build time, and that is the trade-off. A binary built today and launched without the CDN next year runs today's versions, whatever the CDN has shipped since. That is the part of post 1's requirement a copy can meet: the reviewed code runs without the CDN. The Pokémon still come from PokéAPI, so with no network at all the list's request fails and the screen shows its own error, "Couldn't reach PokéAPI."

Nothing about the failure is remembered either. The next launch asks the CDN again, and if a usable map arrives and its versions register, the app is back on the versions the map names.

A remote that fails in a CDN launch

Bundled mode covers a launch that could not use the CDN's versions. The other failure is narrower: the launch uses the CDN's versions, and then one remote fails. The cause might be a version retired from the CDN while a map still names it, a chunk cut off halfway, or a release that throws while its module initialises, which was post 15's third break. In post 15's build each of those leaves one dead tab. Two nets turn them into a tab that runs from its copy, while the other remote stays on the CDN.

The manifest net

Module Federation fetches a remote's mf-manifest.json before any of its code loads. A tab's boundary would hear of that fetch failing, but only once the runtime's own fetch gives up, and the runtime sets no time limit on it. And not every load runs inside a boundary: the party's state and styles modules ask for its manifest at boot, from an effect outside every tab. So the first net sits where the runtime asks for every manifest: a runtime plugin's fetch hook, which the runtime calls before its own fetch, and which may answer with a Response or hand the request back by returning nothing:

const embeddedFallback: ModuleFederationRuntimePlugin = {
  name: 'embedded-fallback',
  fetch(url: string) {
    if (status.mode !== 'cdn') {
      return undefined;
    }
    const remote = manifestRemote(url, REMOTE_NAMES);
    if (!remote || !hasEmbeddedCopy(remote)) {
      return undefined;
    }
    if (fallbackRemotes.has(remote)) {
      return fetch(embeddedManifestUrlFor(remote));
    }
    return cdnManifestOrEmbedded(url, remote);
  },
};
registerPlugins([embeddedFallback]);

A CDN remote's manifest is fetched from the CDN, within the probe's 1.5-second limit. Any failed request (an error status such as a 404, a timeout or a dropped connection) drops that one remote to its copy and answers with the copy's manifest instead:

async function cdnManifestOrEmbedded(url: string, remote: string): Promise<Response> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
  try {
    const response = await fetch(url, { signal: controller.signal });
    if (response.ok) {
      return response;
    }
    console.warn(`[federation] ${remote} manifest returned ${response.status}`);
  } catch (error) {
    console.warn(`[federation] ${remote} manifest could not be fetched`, error);
  } finally {
    clearTimeout(timer);
  }
  fallBack(remote);
  return fetch(embeddedManifestUrlFor(remote));
}

A manifest that arrives with a success status goes back to the runtime as it is, even one that cannot be read. The runtime fails on that afterwards, and for a tab's load the boundary net catches the failure.

fallBack adds the remote to a set and puts it on the banner, as listApp 1.2.0 embedded. The resolver reads that same set for every script, so the remote's very next script resolves to its copy, while every other remote keeps its CDN URL. The set lives in memory on purpose: a remote drops to its copy only until the next launch, which asks the CDN again, so a failure that was only the network does not keep it there. Remembering failures across launches, and rolling a bad version back permanently, belongs to post 17.

Other tools already offer parts of this, and each would work at its own layer. Module Federation's errorLoadRemote hook can return a fallback when a load fails, the manifest included. Its official retry plugin retries a failed load and can rotate between backup domains, and Re.Pack's script locator takes retry and retryDelay. The fetch hook was the fit here for two reasons. errorLoadRemote hears of a failure only after the runtime's fetch gives up, as the boundary does, while the fetch hook makes the request itself and can put the probe's time limit on it. And retrying is a different policy: it spends time asking the same CDN again, where this net answers at once from a copy the binary already has and leaves the next attempt to the next launch. Retries could sit in front of the net, at the cost of a longer wait before the copy.

Try the net with a version the CDN no longer holds. Start the server again, move the list's version out of it, and cold-start the app:

mv cdn-root/ios/listApp/1.2.0 /tmp/listApp-1.2.0

The list's manifest comes back 404, the list runs from its copy, and the party still loads from the CDN, which the server's log shows:

[2026-09-29T14:40:27.102Z]  "GET /ios/listApp/1.2.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-29T14:40:27.103Z]  "GET /ios/listApp/1.2.0/mf-manifest.json" Error (404): "Not found"
[2026-09-29T14:40:27.120Z]  "GET /ios/partyApp/1.0.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-29T14:40:27.159Z]  "GET /ios/partyApp/1.0.0/partyApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"

Move the directory back before going on:

mv /tmp/listApp-1.2.0 cdn-root/ios/listApp/1.2.0

If every remote drops to its copy, check that the app can reach the server. A banner that marks both remotes embedded, or reads bundled, while the server is running usually means the app could not reach it: iOS's App Transport Security and Android's cleartext rules refuse plain http if the build does not allow it. This host allows local networking on iOS and, on Android, cleartext only to localhost, 127.0.0.1 and 10.0.2.2, with their subdomains.

The boundary net

Some failures come after a manifest that arrived fine: a container or a chunk that does not arrive or does not verify, or a module that throws while it is evaluated. They fail the tab's load, and the tab's load runs inside the RemoteBoundary that post 11 put around each tab. The boundary is the second net, and it stays a class component, because React has no way yet to write an error boundary as a function component. It now asks one question before it shows the error state: did the load fail, so the remote never produced a component, and is there a copy this remote has not dropped to yet?

componentDidCatch(error: unknown) {
  console.warn(`${this.props.remote} failed`, error);
  if (this.dropsToCopy()) {
    fallBackAndReload(this.props.remote);
    this.nextAttempt();
  }
}

// A failure the copy in the binary can answer: the load failed, so the remote never produced a
// component, and this remote has a copy it has not dropped to yet.
dropsToCopy() {
  return !this.loaded() && canFallBack(this.props.remote);
}

When it can, the boundary drops the remote to its copy and loads the tab again, rendering the loading state in the meantime, so the error state never appears. canFallBack allows it once per remote, only in a CDN launch, and only for a remote that has a copy. When it cannot, because the copy failed too, or there is none, the tab shows the error state as before.

A remote whose load returned a component keeps its error state when that component throws. That is a decision, and it rests on whether the remote produced a component. Before it does, the tab is still showing its loading state, so a swap to the copy is invisible. Once the load has returned a component, the boundary keeps that version, even when the component throws on its very first render. It records the attempt whose load arrived with a component, not whether the screen was ever shown, so a failure in that attempt counts as thrown by the remote's own code, which has already run in this session. Until the map names a different version, the copy is that same version anyway. So the boundary shows "This tab stopped working" and offers Try again, which renders the remote again and recovers an error that does not repeat. An error that repeats leaves the tab on its error state for the rest of the session, and after a relaunch for as long as the map names that version, even with a working copy in the binary.

The boundary net does not cover the party's two boot modules: they load from an effect outside every tab, so the host only logs a failure the manifest net does not answer. When the state module fails, adding to the party stays disabled until the Party tab loads, because that tab injects the state itself; a failed styles module does not affect adding.

Post 15's third break is now a failed load the copy can answer. Its release throws while its module initialises, and post 15's evaluation window turns that throw into a failed load instead of a fatal report. Build it again. Add the same line below the imports of apps/list/src/PokedexScreen.tsx:

throw new Error('PokedexScreen failed to initialise');

Then ship it as 1.4.0, the way post 15 did:

( cd apps/list && MF_REMOTE_VERSION=1.4.0 npm run bundle:ios:prod ) && rsync -a --exclude '*.map' --exclude mf-stats.json apps/list/cdn/ios/listApp/1.4.0/ cdn-root/ios/listApp/1.4.0/

Delete the line, point the 2.0.0 map at 1.4.0 and relaunch. The tab drops to the 1.2.0 copy: the chip says 1.2.0, the banner marks the list embedded, and the simulator's log has no RCTFatal in it. Put the map back to 1.2.0.

The boundary net also catches a CDN that disappears mid-session. Launch with the server running and leave the Party tab unopened. Add a Pokémon from the Pokédex, stop the server, then open Party for the first time. Only the party's state and styles modules loaded at boot, so its screens are not on the device yet: the download fails, and the tab shows a spinner for a moment and then the party from its copy, with the Pokémon you added and the banner reading partyApp 1.0.0 embedded. Removing the Pokémon there works too, because the copy's screens and the state module that loaded from the CDN share the host's one store.

A Try again that retries

In post 15's build, Try again on a tab whose load failed never brings the tab back. Three records of the failed load stand between Try again and a fresh attempt.

The first is React's. A lazy component calls its load function once: the React documentation says "Both the returned Promise and the Promise's resolved value will be cached, so React will not call load more than once", and a rejection goes to the nearest error boundary. The boundary already handled that, by mounting a new lazy component under a new key for every attempt.

The second is the host bundle's, and it is the one that kept post 15's tabs dead. An import('listApp/ListStack') compiles into a module of the host's own bundle, and the bundle keeps each module it has evaluated for the rest of the session. After a failed load it keeps what the failure left behind, a module with nothing in it, and every later import() settles with that, even when the retry downloads the remote successfully. Measured on an iOS Release build: the retry fetched the manifest and both chunks, and the import still resolved without a component. So the tabs, and the two modules the party loads at boot, no longer use import(). They ask the federation runtime directly, every time:

export async function loadRemoteModule<T>(id: string): Promise<T | undefined> {
  const factory = await loadRemote<() => T>(id, { loadFactory: false, from: 'runtime' });
  return factory ? factory() : undefined;
}

It asks for the module's factory rather than its exports, with loadFactory: false, which is how post 15's evaluation window gets to wrap it: the runtime hands back the window's wrapper, and calling it here evaluates the module inside the window.

The third is the federation runtime's. In @module-federation/runtime-core 2.9.0, the version this series installs, its record of a remote outlives a failed load: it keeps the remote's entry, the manifest it read, the container it loaded, and a container load that failed, which it hands back to every later request. The remote's chunk registry, a global array named after the remote's uniqueName, also keeps every chunk its last container fetched, and a new container installs all of them before fetching anything. Try again clears both before it loads again:

function reloadRemote(remote: RemoteName, entry: string): void {
  try {
    registerRemotes([{ name: remote, entry }], { force: true });
  } catch (error) {
    console.warn(`[federation] ${remote} could not be registered again`, error);
  }
  delete (globalThis as Record<string, unknown>)[CHUNK_REGISTRY[remote]];
}

Registering the remote again with force removes the runtime's record, the container's global included, and points the next load at entry. Try again reads entry back from the runtime instead of building it, which works in every mode, including development, where only the build knows the dev server's URL. A remote that dropped to its copy still retries its copy, because the manifest net and the resolver both send any remote in the set to its copy.

Re.Pack's script cache needs no clearing for a failed load: once a resolved script's load settles, Re.Pack drops its promise, and a download that fails verification is never written to its cache, on either platform. A refusal from the resolver is the exception. It comes before that cleanup, so Re.Pack keeps the rejection and hands it back to every later request for the same script. This host's resolver refuses only a remote it has no version or copy for.

One gap stays open: Try again cannot cancel a download already in flight. A chunk the failed container was still fetching lands in whichever registry exists when it arrives, and when a script is still loading, Re.Pack answers a new request for it with the promise already outstanding. When the copy is the version the CDN was serving, the default, those are the same bytes either way; when the map names a different version, a late chunk from the CDN can land beside the copy's container.

A render error shows Try again recovering a tab whose code has already loaded. The boundary net's mid-session demo stopped the server, so start it again and leave it running:

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

Then make the list's screen throw while it renders, for its first eight seconds. Below the imports of apps/list/src/PokedexScreen.tsx add:

const LOADED_AT = Date.now();

and as the first lines of PokedexScreen():

if (Date.now() - LOADED_AT < 8000) {
  throw new Error('PokedexScreen render failed');
}

The throw has to last: React retries a render that fails, so an error that stops too soon recovers before the boundary's error state is ever shown. Ship it as its own version, the way 1.4.0 shipped, then delete the lines and point the 2.0.0 map at 1.5.0:

( cd apps/list && MF_REMOTE_VERSION=1.5.0 npm run bundle:ios:prod ) && rsync -a --exclude '*.map' --exclude mf-stats.json apps/list/cdn/ios/listApp/1.5.0/ cdn-root/ios/listApp/1.5.0/

Relaunch and the tab shows "This tab stopped working". Wait out the eight seconds and press Try again: the list renders on 1.5.0, and the server's log shows no new request, because the code had loaded and only needed rendering again. Put the map back to 1.2.0 afterwards.

🎞️ Animated demo: watch it on warrendeleon.com

The failures and what each one costs, side by side:

Failure	Caught by	What the user sees
The CDN cannot be reached at launch	the launch, in bundled mode	every tab from its copy, and a purple banner
A remote's manifest fails: a 404, a timeout, a dropped connection	the manifest net	the tab from its copy, marked `embedded` on the banner
A tab's remote code does not arrive, does not verify, or throws as its module initialises	the boundary net	a moment of loading, then the tab from its copy
The party's state module fails at boot, once its manifest has arrived	nothing: the host logs it	adding to the party stays disabled until the Party tab loads
The party's styles module fails at boot, once its manifest has arrived	nothing: the host logs it	adding still works
The copy fails as well, or there is no copy	the boundary	"This tab could not load", with Try again
The remote's component throws as it renders	the boundary	"This tab stopped working", with Try again

Now break it

Both embed steps succeed without embed-root/, and that is the trap. Move it out and rebuild the Release build, this time with --verbose:

mv embed-root /tmp/embed-root && ( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release --verbose )

The build succeeds, and the phase's warning is the only sign that anything is missing. Without --verbose, npm run ios shows a spinner in place of the build's output (or passes the output through xcbeautify or xcpretty, when one is installed), then reports success Successfully built the app and launches. With --verbose, the warning sits among the build's own lines:

debug warning: …/embed-root/ios does not exist, so no remotes are embedded. Run 'node tools/build-cdn.mjs' before a release build.
debug ** BUILD SUCCEEDED ** [11.716 sec]
success Successfully built the app

Stop the server and cold-start the app. The banner still says bundled · listApp 1.2.0 · partyApp 1.0.0, because the host compiled in the versions it was told it carries, and both tabs say "The app's own copy of this remote could not be loaded".

Build the CDN tree, then the release build, every time. The embed phases copy whatever embed-root/ holds when they run, and when it is missing they let the build succeed with nothing more than a warning in the build's output. A release build made before node tools/build-cdn.mjs, or after embed-root/ was cleaned, builds successfully with no copy in it, and nothing fails until the app needs a copy: when the launch cannot use the CDN's versions, or when one remote fails.

Move it back and rebuild before going on:

mv /tmp/embed-root embed-root && ( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release )

Run it

The copies and the CDN tree, then the server:

node tools/gen-signing-keys.mjs && node tools/build-cdn.mjs

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

The Release build on iOS, then Android with the emulator's address for the machine:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release )

( cd apps/host && MF_CDN_BASE=http://10.0.2.2:8000 MF_APP_VERSION=2.0.0 npm run android -- --mode release )

With either running, stop the server and cold-start for bundled mode, or move one version out of cdn-root for the manifest net. On Android the extracted copies sit in the app's files directory, under files/cdn/android/, with the .installed marker beside them in files/cdn/.

The suites, the smoke test and the key generator's tests:

( for d in apps/host apps/list apps/party packages/ui; do ( cd "$d" && npx jest --silent ) || exit 1; done ) && sh scripts/federation-smoke.sh && node --test tools/gen-signing-keys.test.mjs

What you built, and what's next

The demos in this post ran on an iOS Release build, and the copies, their extraction and bundled mode on an Android release build as well.

A remote that fell back is forgotten at the next launch, so a version that keeps failing fails again on every launch before its copy takes over. Remembering failures belongs with the other open problem: the map every binary trusts is still a plain text file anyone who can write to the bucket can change.

Next: signing that map, a counter that makes the app reject an older map, and an app that rolls a failing version back by itself.

Sources

React: lazy — the load function called once, its promise and resolved value cached, and a rejection thrown to the nearest error boundary
React source: ReactLazy at 19.2.3 — a rejected load stored on the lazy component and thrown again on every later render
React: Component, catching rendering errors with an error boundary — "There is currently no way to write an Error Boundary as a function component"
Module Federation: runtime hooks — the fetch hook for manifest requests, returning Promise<Response> | void | false, and errorLoadRemote
Module Federation source: runtime-core SnapshotHandler at 2.9.0 — a manifest asked of the fetch hook first, then of the global fetch, then of errorLoadRemote on failure
Module Federation source: runtime-core remote/index.ts and utils/load.ts at 2.9.0 — registerRemotes with force calling removeRemote, which deletes the remote's entry, manifest, container global and container-loading promise; a failed container load's promise kept and returned to later loads until then
Module Federation: retry plugin — retries and backup domains for failed loads
Re.Pack source: ScriptManager types at 5.2.5 — the locator's absolute, retry and retryDelay
Re.Pack source: ScriptManager.ts at 5.2.5 — a resolved script's promise deleted once its load settles, failed or not; a resolver's rejection comes before that cleanup and is kept
Re.Pack source: ScriptManager.mm at 5.2.5 — a file:// script read at its absolute path, or by name through URLForResource:withExtension:, and verified before it runs; a download written to the cache only after it verifies
Re.Pack source: FileSystemScriptLoader.kt and RemoteScriptLoader.kt at 5.2.5 — the same on Android, with an asset opened by its file name when the path is not absolute, and a download verified before it is written
Apple: URLForResource:withExtension: — a resource looked up by name in the bundle, beside the variant that takes a subdirectory
swift-build source: ShellScriptTaskProducer.swift at swift-6.2.1-RELEASE — a Run Script phase that declares no outputs, or is set to run always, runs on every build
React Native CLI source: buildProject.ts at 20.2.0 — without --verbose, the build's output piped through xcbeautify or xcpretty when one is installed, and a spinner otherwise
React Native source: RCTSourceCode.mm at 0.85.3 — scriptURL, the URL the JavaScript bundle loaded from
React Native source: RCTFileRequestHandler.mm and RCTAppSetupUtils.mm at 0.85.3 — file:// requests answered on iOS, and the handler registered with the app's networking
React Native source: BlobModule.kt at 0.85.3 — any URL that is not http or https, read on Android when the response type is blob
Android: AssetManager — assets opened and listed from the APK, not as files
Gradle: Sync — a copy that also removes files the source no longer has
react-native-module-federation — the companion repo, the build at the tag post-16-fallbacks

CDN delivery: the version map, the resolver, and the live flip

Warren de Leon — Mon, 12 Oct 2026 00:03:52 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 14 ended on a promise: "versioned remotes on the CDN, a version map, a per-launch resolver, and an old binary that never downloads code it cannot run." This post builds that, then uses it. An app sits installed with its dev servers off, showing version 1.1.0 of the Pokédex list. You ship it 1.2.0 with one directory and one edited line of JSON, watch the change arrive at its next launch, and roll it back the same way.

The operation needs three pieces. A content delivery network (CDN) keeps every published version of each remote, so a new version never replaces files an installed app is loading. A map for each released app version tells that binary which of those versions to load. A resolver in the host turns every chunk request into a versioned, signature-verified URL. Together they deliver what post 1 said federation gives you: "A bug in one remote is a re-upload of that remote, not a store submission."

One rule shapes all of it: an old binary must keep working for as long as anyone has it installed. The CDN keeps old remote versions the way a backend keeps old endpoints, and each binary is handed only the versions its own map names. Nothing on the device checks that those versions work with the binary: choosing versions it has been tested with is the operator's job, and the map is where that choice is written down.

Start from post 14's finished state, the tag post-14-production-build; this post finishes at the tag post-15-cdn-flip. You type the configuration changes and the smaller edits yourself. The host's new launch code and a handful of other files change in more places than a post can usefully retype, so those come from the end tag, and the copy commands name each one.

📊 Diagram: view it on warrendeleon.com

The map is fetched before anything federated is imported, and every request after it carries the version the map named.

Versions on the shelf

A version has to reach three places in a remote's build, and they have to agree: the directory the artefacts are written to, the directory the chunks are written to, and the string the running screen prints about itself. One constant feeds all three. In apps/list/rspack.config.mjs, above defineRspackConfig:

// --- Which version of this remote the build produces. It decides two things at once: the
// directory the artefacts are written to, and the string the running code reports about itself.
// Both come from one variable, so a build cannot write 1.2.0's files and claim to be 1.1.0:
//   MF_REMOTE_VERSION=1.2.0 npm run bundle:ios:prod
// A version directory is written once and never edited afterwards. Rebuilding a version that
// installed apps are already loading replaces code those apps treat as fixed, which is the one
// move this layout exists to make unnecessary: ship a new version instead. ---
const REMOTE_VERSION = process.env.MF_REMOTE_VERSION || '1.0.0';

Post 14's two production paths each gain the segment. In output:

// A production build writes the tree the CDN serves, laid out as the URL path it is served
// at: cdn/<platform>/listApp/<version>/. The version segment is what lets one CDN hold
// several releases of this remote at once, each at its own URL. A development build keeps
// writing to build/, where the dev server reads it from, and carries no version: there is
// only ever one build there, and it is whatever was saved last.
path: isProd
  ? `${__dirname}/cdn/[platform]/listApp/${REMOTE_VERSION}`
  : `${__dirname}/build/[platform]`,

and in the RepackPlugin's extraChunks entry:

// The chunks land beside the container and the manifest, inside the same version
// directory, because the host will ask for them at URLs relative to the manifest it
// loaded. This entry copies them there: Rspack has already written them under
// output.path, so a missing version segment here breaks nothing at runtime, and
// instead leaves a second, unversioned copy of every chunk beside the versions.
outputPath: isProd
  ? `cdn/${platform}/listApp/${REMOTE_VERSION}`
  : `build/${platform}/remote`,

The third place is a literal compiled into the bundle. Add DefinePlugin to the @rspack/core import beside the minimiser, and a plugin entry before ModuleFederationPluginV2:

import { DefinePlugin, SwcJsMinimizerRspackPlugin } from '@rspack/core';

// The version, compiled into the bundle as a literal so the running screen can print the
// build it came from. In production it is read from the same constant the output path uses,
// so the chip on screen and the directory on the CDN can never disagree. A development
// build says 'dev' instead: it was never published anywhere, and a number on it would be a
// version claim about a file that is rebuilt on every save.
new DefinePlugin({
  __REMOTE_VERSION__: JSON.stringify(isProd ? REMOTE_VERSION : 'dev'),
}),

Mirror the two paths in apps/party/rspack.config.mjs with partyApp. Its constant carries a comment of its own, because the party has no chip and so needs no DefinePlugin:

// --- Which version of this remote the build produces, and the directory it is written to. Same
// variable, same rule as listApp's: a version directory is written once and never edited after
// installed apps have started loading it. ---
const REMOTE_VERSION = process.env.MF_REMOTE_VERSION || '1.0.0';

Back in the list app, TypeScript needs a declaration for __REMOTE_VERSION__, because the name has no module behind it. A new apps/list/src/globals.d.ts provides one:

// --- Names the bundler replaces with literals at build time, declared for the compiler. They
// are not imports and there is no module behind them: rspack.config.mjs substitutes each one
// during the build, so the shipped bundle contains the value and never the name. ---

/** The version of this remote the build produced, and the CDN directory it was written to. */
declare const __REMOTE_VERSION__: string;

The chip is what makes a deploy visible, because two builds of the same remote are otherwise the same screen. In apps/list/src/PokedexScreen.tsx, above EMPTY_TYPES:

// --- The version this bundle was built at, compiled in by DefinePlugin. Showing it is what
// makes a deploy visible: two builds of this remote are otherwise the same screen, so without
// it there is no way to tell from the app which one is running. The fallback covers Jest, where
// no bundler runs and the name is never substituted. ---
const REMOTE_VERSION = typeof __REMOTE_VERSION__ === 'string' ? __REMOTE_VERSION__ : 'dev';

The header row becomes the chip on the left and the party counter on the right. The chip is its own accessible element, so a screen reader can reach it without hearing the party count first. The live region and its label move off the row onto a group of their own around post 12's label and pill, so the row no longer swallows the chip:

ListHeaderComponent={
  <Box className="flex-row items-center justify-between px-1.5 py-2.5">
    {/* Which build of this remote is on screen. Its own element rather than part of the
        counter's group, so a screen reader can reach it without it being read out every
        time the party count changes. */}
    <Box
      className="rounded-full bg-offGrey px-2 py-0.5 dark:bg-white/10"
      accessible
      accessibilityLabel={`Pokédex remote, version ${REMOTE_VERSION}`}>
      <Text size="xs" className="font-semi text-darkGrey dark:text-lightGrey">
        listApp {REMOTE_VERSION}
      </Text>
    </Box>
    {/* The count changes when the user adds a member from a screen away, without focus
        moving here. A sighted user sees the number tick; a screen-reader user is told
        nothing unless this is a live region (SC 4.1.3). The label spells the ratio out,
        because "3/6" is read as "three slash six" or as a date, depending on the reader. */}
    <Box
      className="flex-row items-center gap-2"
      accessible
      accessibilityLiveRegion="polite"
      accessibilityLabel={`My Party, ${partyCount} of ${MAX_PARTY}`}>
      <Text size="sm" className="font-semi text-darkGrey dark:text-lightGrey">
        My Party
      </Text>
      <Box className="rounded-full bg-lightGreen px-2.5 py-0.5 dark:bg-white/10">
        {/* darkGrey, not darkGreen: darkGreen is #A6D3A0, the grass fill, and on lightGreen
            it measures 1.53:1. darkGrey is the colour the label beside it already uses. */}
        <Text size="xs" className="font-head text-darkGrey dark:text-pokemonGreen">
          {partyCount}/{MAX_PARTY}
        </Text>
      </Box>
    </Box>
  </Box>
}

Post 14's tools/build-cdn.mjs built one version of each remote into a flat tree. Replace it with one that starts from two lists. REMOTE_VERSIONS says which versions of each remote the CDN holds. APP_VERSION_MAPS says which of those versions each released app version loads. A version can sit in the first list with no map pointing at it:

// --- Assembles the directory a CDN would serve.
//
// The layout is the URL layout, and it now has a version in it:
//
//   cdn-root/<platform>/<remote>/<version>/     the container, its chunks and mf-manifest.json
//   cdn-root/<platform>/maps/<appVersion>/      version-map.json, one per released app version
//
// A file at cdn-root/ios/listApp/1.2.0/mf-manifest.json is served at
// <base>/ios/listApp/1.2.0/mf-manifest.json, which is the URL the host builds at launch out of
// the version the map gave it.
//
// Two lists below, and the difference between them is the whole idea. REMOTE_VERSIONS is what the
// CDN holds: every version ever published, kept until nobody is running it. APP_VERSION_MAPS is
// what each released binary is allowed to load out of that. Shipping a remote to installed apps
// is a new entry in the first list and one edited line in the second.
//
// Usage: node tools/build-cdn.mjs [ios|android]     (no argument builds both)
//
// Then serve it and point the host at it (an Android emulator reaches this machine at 10.0.2.2,
// so the Android build gets that address instead of localhost):
//   npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors
//   ( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm start )

import { execSync } from 'node:child_process';
import { cpSync, existsSync, mkdirSync, rmSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
const REMOTE_APPS = { listApp: 'list', partyApp: 'party' };
const ALL_PLATFORMS = ['ios', 'android'];

// --- Every version of each remote the CDN holds. A version directory is written once and then
// left alone: installed apps are loading those exact files, so a rebuild of a published version
// is a silent change to code somebody is already running. New work gets a new number.
//
// listApp has two: 1.0.0 and 1.1.0 are the same screen with different stamps on it, which is
// what the two-binaries demo needs. The flip to 1.2.0 adds the third. ---
const REMOTE_VERSIONS = {
  listApp: ['1.0.0', '1.1.0'],
  partyApp: ['1.0.0'],
};

// --- What each released app version may load. The host asks for its own entry by name at every
// launch, so an old binary keeps being handed the versions it was built against, however far the
// newest release has moved on. An entry is retired when nobody is left on that app version, the
// same way an old API endpoint is.
//
// Editing a line here rebuilds the whole tree, which is the wrong tool for shipping a version:
// the operation the post performs is an edit to the map file already sitting in cdn-root,
// because that file is what a running app reads. This is the seeding of a CDN, not an operation
// against one.
//
// There is nothing else in the map. No signature over it, no counter, nothing that would let the
// app tell a map written here from one written by anybody else who can reach the bucket. That is
// a real hole and it is left open on purpose: it is the subject of the last post in the series. ---
const APP_VERSION_MAPS = {
  '1.0.0': { listApp: '1.0.0', partyApp: '1.0.0' },
  '2.0.0': { listApp: '1.1.0', partyApp: '1.0.0' },
};

// --- Never published: source maps are four fifths of the built tree, they are a debugging
// artefact for a crash reporter rather than something a client downloads, and on a public bucket
// they hand the whole readable source to anyone who asks for it. mf-stats.json is build analysis
// in the same position. The remote's own index.bundle stays, because mf-manifest.json names it
// among the shared assets and nothing here has established that no path fetches it. ---
const NEVER_PUBLISHED = /\.map$|^mf-stats\.json$/;

const [platformArg] = process.argv.slice(2);
if (platformArg && !ALL_PLATFORMS.includes(platformArg)) {
  console.error(`Unknown platform "${platformArg}". Use one of: ${ALL_PLATFORMS.join(', ')}`);
  process.exit(1);
}
const platforms = platformArg ? [platformArg] : ALL_PLATFORMS;

// --- A map naming a version the CDN does not hold is the failure the post demonstrates by hand,
// and it is worth catching here rather than at a user's launch. Checked before anything is built,
// so a typo costs a second instead of two bundle runs. ---
const unknownRemotes = Object.keys(REMOTE_VERSIONS).filter(remote => !REMOTE_APPS[remote]);
if (unknownRemotes.length > 0) {
  console.error(
    `\nNo app to build for: ${unknownRemotes.join(', ')}. Add it to REMOTE_APPS, or remove it from REMOTE_VERSIONS.\n`,
  );
  process.exit(1);
}

const missing = Object.entries(APP_VERSION_MAPS).flatMap(([appVersion, versions]) =>
  Object.entries(versions)
    .filter(([remote, version]) => !REMOTE_VERSIONS[remote]?.includes(version))
    .map(([remote, version]) => `  app ${appVersion} asks for ${remote} ${version}`),
);
if (missing.length > 0) {
  console.error('\nThese versions are mapped but not published:');
  console.error(missing.join('\n'));
  console.error('\nAdd them to REMOTE_VERSIONS, or point the map at a version that exists.\n');
  process.exit(1);
}

for (const platform of platforms) {
  // Wipe this platform only, so building one does not delete the other's tree.
  rmSync(join(repoRoot, 'cdn-root', platform), { recursive: true, force: true });
  mkdirSync(join(repoRoot, 'cdn-root', platform), { recursive: true });

  for (const [remote, versions] of Object.entries(REMOTE_VERSIONS)) {
    const appDir = join(repoRoot, 'apps', REMOTE_APPS[remote]);
    for (const version of versions) {
      console.log(`\n=== building ${remote} ${version} (${platform}) ===`);
      // Named once: the directory that is cleared, written and then read is one place, so no
      // later edit can move the build's output out from under the copy that follows it.
      const built = join(appDir, 'cdn', platform, remote, version);
      // Cleared first, because Rspack writes into a directory rather than replacing it, so a file
      // an earlier build emitted and this one does not would survive and be published beside the
      // real ones, for no reason anyone could work out from the source.
      rmSync(built, { recursive: true, force: true });
      // MF_REMOTE_VERSION decides both what the bundle says about itself and where it is written,
      // so one variable cannot produce a build that is stamped one version and filed under another.
      execSync(`npm run bundle:${platform}:prod`, {
        cwd: appDir,
        stdio: 'inherit',
        env: { ...process.env, MF_REMOTE_VERSION: version },
      });
      // The build reported success, so a missing directory here means its output path and this
      // path have drifted apart, which is worth saying in one line rather than as a stack trace.
      if (!existsSync(built)) {
        console.error(`\n${remote} built but wrote nothing to ${built}.`);
        console.error("Check the output path in that app's rspack.config.mjs.\n");
        process.exit(1);
      }
      cpSync(built, join(repoRoot, 'cdn-root', platform, remote, version), {
        recursive: true,
        filter: source => !NEVER_PUBLISHED.test(source.split('/').pop()),
      });
      console.log(`published -> cdn-root/${platform}/${remote}/${version}`);
    }
  }

  for (const [appVersion, versions] of Object.entries(APP_VERSION_MAPS)) {
    const dir = join(repoRoot, 'cdn-root', platform, 'maps', appVersion);
    mkdirSync(dir, { recursive: true });
    writeFileSync(join(dir, 'version-map.json'), `${JSON.stringify(versions, null, 2)}\n`);
    console.log(`wrote     -> cdn-root/${platform}/maps/${appVersion}/version-map.json`);
  }
}

const HOST_ADDRESS = { ios: 'http://localhost:8000', android: 'http://10.0.2.2:8000' };
const appVersions = Object.keys(APP_VERSION_MAPS);
console.log(`\nCDN assembled at ${join(repoRoot, 'cdn-root')}`);
console.log('Serve it:             npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors');
for (const platform of platforms) {
  console.log(
    `Point the host at it: ( cd apps/host && MF_CDN_BASE=${HOST_ADDRESS[platform]} MF_APP_VERSION=${appVersions.at(-1)} npm start )   # ${platform}`,
  );
}
console.log(`App versions with a map: ${appVersions.join(', ')}`);

Source maps stop being published: they are four fifths of a built remote (16 MB of the 20 MB listApp writes on iOS), a crash reporter's artefact rather than a client's download, and on a public bucket they hand the readable source to anyone who asks. Build the tree:

node tools/build-cdn.mjs ios

cdn-root/ios/listApp/1.0.0/      cdn-root/ios/maps/1.0.0/version-map.json
cdn-root/ios/listApp/1.1.0/      cdn-root/ios/maps/2.0.0/version-map.json
cdn-root/ios/partyApp/1.0.0/

Each map is the whole of what a binary is told:

{
  "listApp": "1.1.0",
  "partyApp": "1.0.0"
}

Two lines and nothing else. The chunks it points at are signed; the file that chooses between them is not. Post 17 closes that; this post leaves it open and says so each time it matters.

Ask before you load

The host needs two facts at build time: where the CDN is, and which app version this binary is. In apps/host/rspack.config.mjs, post 14's comment and const CDN_BASE = process.env.MF_CDN_BASE; become:

// --- Where the remotes are served from. Set MF_CDN_BASE and the host looks to the content
// delivery network instead of the dev servers; leave it unset and nothing changes. The value is
// read at BUILD time and baked into the bundle, so a build that forgot it ships the dev URLs:
//   MF_CDN_BASE=http://localhost:8000 npm start      (the local CDN, on a development build)
//   MF_CDN_BASE=https://cdn.example.com npm run …    (a real one, on a release build)
//
// What changed in this post is who uses the value. It still shapes the remotes map below, but
// that map is now a placeholder: the URLs it holds carry no version segment, so against a
// versioned CDN tree they resolve to nothing. The value that matters is the one handed to the
// running code through DefinePlugin, where src/shell/scriptManager.ts reads it, asks the CDN
// which versions this binary may run, and re-registers every remote at a versioned URL before
// the first import fires.
// Trailing slashes are trimmed, because every URL built from this value adds its own separator
// and a base written with one produces a double slash in the middle of every path. Most servers
// forgive that; a downloaded script is cached against the URL that fetched it, so it is not worth
// finding out which ones do not.
const CDN_BASE = (process.env.MF_CDN_BASE || '').replace(/\/+$/, '');

// --- This binary's own version, the question it asks the CDN at launch. The CDN answers with the
// remote versions this binary is allowed to run, which is how a two-year-old install keeps
// working: it keeps being handed the versions it shipped against. A real app reads this from the
// version it was released under; here it is a variable, so one checkout can produce two binaries
// that ask different questions:
//   MF_APP_VERSION=1.0.0 npm run ios -- --mode Release
const APP_VERSION = process.env.MF_APP_VERSION || '1.0.0';

Both facts reach the running code as literals: add DefinePlugin to the host's @rspack/core import, and this entry to plugins before ModuleFederationPluginV2:

// The two build-time facts the operational layer needs as literals in the bundle: where the
// CDN is, and which version this binary is. An empty base is the signal that no CDN was
// configured, which is what keeps a plain development build on the dev servers.
new DefinePlugin({
  __MF_CDN_BASE__: JSON.stringify(CDN_BASE),
  __APP_VERSION__: JSON.stringify(APP_VERSION),
}),

Post 14's remoteUrl function and the remotes map stay, and their job changes. Module Federation wants a name and an entry for every remote declared at build time, so the map stays; its URLs carry no version, so against a versioned tree they resolve to nothing. The comment above the function says so:

// The build-time remotes map, in one function: dev server or CDN, same manifest filename either
// way. In CDN mode what it produces is a placeholder and nothing loads from it: the versioned
// URL the app really uses is decided at launch. It is left pointing somewhere plausible rather
// than removed, because Module Federation wants a name and an entry for every remote declared
// at build time, and because in dev mode this is still the whole story.
const remoteUrl = name =>
  CDN_BASE
    ? `${name}@${CDN_BASE}/${platform}/${name}/mf-manifest.json`
    : `${name}@${DEV_REMOTES[name]}/${platform}/mf-manifest.json`;

In CDN mode the build-time map is a placeholder. The URL the app really uses is decided at launch, by host code you copy from the end tag rather than type. Fetch the tag once; the copy commands take that code with its tests and Jest stand-ins, plus the other files later sections use:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-15-cdn-flip /tmp/pokedex-ref-15

cp /tmp/pokedex-ref-15/apps/host/src/shell/{remoteLocator,scriptManager,federationErrors}.ts /tmp/pokedex-ref-15/apps/host/src/shell/FederationBanner.tsx apps/host/src/shell/
cp /tmp/pokedex-ref-15/apps/host/__mocks__/{repack-client,module-federation-runtime}.js apps/host/__mocks__/
cp /tmp/pokedex-ref-15/apps/host/__tests__/{remoteLocator,scriptManager,federationErrors}.test.ts /tmp/pokedex-ref-15/apps/host/__tests__/{App,RemoteBoundary}.test.tsx apps/host/__tests__/
cp /tmp/pokedex-ref-15/apps/host/App.tsx apps/host/
cp /tmp/pokedex-ref-15/scripts/federation-smoke.sh scripts/
cp /tmp/pokedex-ref-15/packages/ui/src/tokens/__tests__/contrast.accessibility.ts packages/ui/src/tokens/__tests__/
cp /tmp/pokedex-ref-15/tools/gen-signing-keys.mjs /tmp/pokedex-ref-15/tools/gen-signing-keys.test.mjs tools/

Read them in the order they run. src/shell/scriptManager.ts is the launch, and its first job is fetching the map. Every federated import waits for that answer, so the request needs a bounded wait: without one, a slow CDN would hold the app at its splash screen for as long as the network let it. The wait is a second and a half:

const PROBE_TIMEOUT_MS = 1500;

An AbortController and a timer enforce it, wired by hand because React Native offers no shortcut. AbortSignal.timeout() does not exist there: 0.85 installs AbortController and AbortSignal from the abort-controller package, which has no timeout. The request has no timeout of its own either: React Native builds Android's HTTP client with every timeout at zero, and on iOS passes the request's timeout through, which defaults to zero:

// --- Fetch and read the version map for this app version. Returns null for every kind of
// failure, because the caller treats them all the same way: an unreachable CDN, a 404 for an app
// version nobody published a map for, a timeout, and a map that does not parse all end with this
// binary running no remotes. ---
async function fetchVersionMap(): Promise<Record<string, string> | null> {
  const controller = new AbortController();
  const timer = setTimeout(() => controller.abort(), PROBE_TIMEOUT_MS);
  try {
    const response = await fetch(versionMapUrl(CDN_BASE, Platform.OS, APP_VERSION), {
      signal: controller.signal,
      // The map is the one file on the CDN that must never be served from a cache: it is the
      // record of what is current, and a stale copy is a silently undone deploy. Every other file
      // the app fetches carries its version in the URL and can be cached forever.
      headers: { 'cache-control': 'no-cache' },
    });
    if (!response.ok) {
      console.warn(`[federation] version map returned ${response.status}`);
      return null;
    }
    const versions = parseVersionMap((await response.json()) as unknown, REMOTE_NAMES);
    if (!versions) {
      // The one failure that is nobody's network and nobody's outage: the file was served and
      // could not be believed. Said out loud, because the alternative is an app that launches,
      // loads nothing and offers no reason.
      console.warn('[federation] version map was served but could not be read');
    }
    return versions;
  } catch (error) {
    console.warn('[federation] version map could not be fetched', error);
    return null;
  } finally {
    clearTimeout(timer);
  }
}

With the versions in hand, every remote is pointed at the manifest inside its version directory:

// --- Point every remote at the versioned manifest this launch resolved.
//
// force is not optional. Each remote is already registered under its name from the build-time
// remotes map, and registerRemotes leaves an already-registered name alone unless it is told
// otherwise: without the flag this call returns quietly, changes nothing, and the app loads the
// unversioned placeholder URLs instead. With it, Module Federation logs a warning about
// re-registering a remote on every launch, which is the expected cost of doing this. ---
function registerCdnRemotes(versions: Record<string, string>): void {
  registerRemotes(
    REMOTE_NAMES.filter(name => versions[name]).map(name => ({
      name,
      entry: remoteManifestUrl(CDN_BASE, Platform.OS, name, versions[name]),
    })),
    { force: true },
  );
}

registerRemotes without force is a silent no-op for a name that is already registered. In Module Federation's runtime core at 2.9.0, the branch for an existing name does nothing at all when force is absent: no error, no warning, no change. The build-time map registered both remotes long before the probe ran, so every launch re-registers with { force: true }, and the runtime prints [ Federation Runtime ]: The remote "listApp" is already registered. Please note that overriding it may cause unexpected errors. once per remote in the development console. That line is the arrangement working. A launch that does not print it loaded the placeholders.

The launch is one function, held as a promise so that a second caller arriving mid-probe waits for the same answer instead of reading the state from before it started:

export function initializeFederation(): Promise<FederationStatus> {
  initialization ??= resolveFederation();
  return initialization;
}

async function resolveFederation(): Promise<FederationStatus> {
  if (!CDN_CONFIGURED) {
    status = __DEV__
      ? { mode: 'dev', source: 'dev servers', versions: {} }
      : { mode: 'unresolved', source: 'no CDN configured', versions: {} };
    return status;
  }

  const versions = await fetchVersionMap();
  if (!versions) {
    // Worded to cover every way this fails, because the banner is a claim the app makes about
    // itself: a map that was served and refused is not an unreachable one, and the log line
    // beside it already says which of the two happened.
    status = { mode: 'unresolved', source: 'no usable version map', versions: {} };
    return status;
  }

  // The status is set before the registration because the resolver reads it, and then rolled back
  // if the registration throws. Claiming CDN mode after a failed re-registration would put the
  // versions on the banner while every load went to the build-time placeholder URL: an app that
  // says it is running 1.2.0 and is running nothing.
  status = { mode: 'cdn', source: CDN_BASE, versions };
  try {
    registerCdnRemotes(versions);
  } catch (error) {
    console.warn('[federation] remotes could not be re-registered', error);
    status = { mode: 'unresolved', source: 'remotes could not be registered', versions: {} };
  }
  return status;
}

Three modes come out of it: dev is post 14's world, cdn is the one this post exists for, and unresolved is a failure with a name: no usable map, so no remote at all, refused rather than loaded unverified. FederationBanner.tsx paints the mode and the resolved versions as a pill above the tab bar, so a demo can be photographed rather than believed.

The gate is in App.tsx. The navigator's tabs are React.lazy federated imports, so mounting the navigator starts the first download, and that must wait for the re-registration. The state and the effect sit in App above SafeAreaProvider, because that provider renders no children until it has measured the insets: below it, the gate would wait on that measurement, and under Jest, where nothing measures, it would never open:

const [federationReady, setFederationReady] = useState(false);

useEffect(() => {
  let live = true;
  initializeFederation()
    .catch(err => console.warn('federation initialisation failed', err))
    .then(() => {
      if (live) {
        setFederationReady(true);
      }
    });
  return () => {
    live = false;
  };
}, []);

{federationReady ? (
  <>
    <Shell navTheme={navTheme} mode={mode} onReady={() => setNavReady(true)} />
    <FederationBanner />
  </>
) : null}

Post 8's boot import of partyApp/partySlice moves behind the same flag, because it is a federated load like any other. After that move, nothing federated loads before the launch has its answer.

A failed probe does not keep the app at its splash screen. The gate opens either way, at most one probe timeout later, and the mode records the difference: after a failed probe the banner shows unresolved, the resolver refuses every remote, and each tab shows its error state.

The host's tests need two more entries in apps/host/jest.config.js, because ScriptManager.shared reaches for a bundler runtime the moment it is touched, and a Jest process has none. The map and the comment above it become:

// Reanimated drives animations through the JSI (the JavaScript Interface React Native uses to
// call native code), which a Jest process has no runtime for, so it is replaced by the stand-in
// in __mocks__. One entry covers the whole federation: @pokedex/ui and @pokedex/detail import
// the same module specifier, so their animated components resolve to the same mock. The
// federated state module has no resolvable source under Jest either; its mock repeats the real
// module's side effect (reducer injection) so boot readiness is testable.
// The Re.Pack client and Module Federation runtime entries exist because Re.Pack's ScriptManager
// and Module Federation's registerRemotes both reach into a bundler runtime that a Jest process
// does not have, and the host touches both at module scope, so the resolver is in place before
// any federated import can fire. Their stand-ins record what was asked of them.
moduleNameMapper: {
  '^react-native-reanimated$': '<rootDir>/__mocks__/react-native-reanimated.js',
  '^partyApp/partySlice$': '<rootDir>/__mocks__/partyApp-partySlice.js',
  '^partyApp/styles$': '<rootDir>/__mocks__/partyApp-styles.js',
  '^@callstack/repack/client$': '<rootDir>/__mocks__/repack-client.js',
  '^@module-federation/runtime$': '<rootDir>/__mocks__/module-federation-runtime.js',
},

One resolver, every chunk

The map names a version per remote. Something still has to turn every script the federation loads into a URL inside that version's directory: the container when the remote is first imported, then each chunk the container asks for. Re.Pack's ScriptManager asks its resolvers in priority order, and the first to return a locator wins. This post adds one. Its decisions live in src/shell/remoteLocator.ts as plain functions, testable without a device, and each script gets one of three answers:

/** The resolver's decision for one script. */
export type Resolution =
  | { kind: 'defer' }
  | { kind: 'locate'; locator: RemoteLocator }
  | { kind: 'refuse'; reason: string };

Which one depends on the mode, the remote and the map:

// --- Which remote a script belongs to. A container announces itself: its script id IS the remote
// name. A chunk does not, so the caller is the only thing that says where it came from, and it is
// why the resolver takes both arguments rather than pattern-matching the id. ---
function remoteFor(
  scriptId: string,
  caller: string | undefined,
  remoteNames: readonly string[],
): string | undefined {
  if (remoteNames.includes(scriptId)) {
    return scriptId;
  }
  if (caller && remoteNames.includes(caller)) {
    return caller;
  }
  return undefined;
}

// --- Decide one script: locate it inside its version's directory, refuse it, or defer it to
// Re.Pack's own resolution.
//
// Deferring hands the script to the next resolver, and for one of this host's remotes the next
// one is Re.Pack's per-remote resolver: it answers with a URL built from whichever manifest was
// registered last and no signature check at all. That is the right answer in development, where
// the dev servers own everything, and for any script that is not one of this host's remotes.
// Outside development it is never the right answer for a remote: with no version map, or a map
// that named no version for this remote, deferring would load code from an unversioned URL,
// unverified. So those loads are refused, and the refusal surfaces as the tab's error state. ---
export function resolveRemoteLocator(input: ResolveInput): Resolution {
  if (input.mode === 'dev') {
    return { kind: 'defer' };
  }
  const remoteName = remoteFor(input.scriptId, input.caller, input.remoteNames);
  if (!remoteName) {
    return { kind: 'defer' };
  }
  const version = input.mode === 'cdn' ? input.versions[remoteName] : undefined;
  if (!version) {
    return {
      kind: 'refuse',
      reason:
        input.mode === 'cdn'
          ? `the version map named no version for ${remoteName}`
          : `no version map was read at launch, so ${remoteName} has no version to load`,
    };
  }
  const filename =
    input.scriptId === remoteName
      ? `${remoteName}.container.js.bundle`
      : `${input.scriptId}.chunk.bundle`;
  return {
    kind: 'locate',
    locator: {
      url: `${input.cdnBase}/${input.platform}/${remoteName}/${version}/${filename}`,
      // Caching is per URL, and a URL here carries its version, so a cached file can only ever be
      // served for the version it was fetched for. A new version is a new URL and a fresh download.
      cache: true,
      verifyScriptSignature: input.verify,
    },
  };
}

📊 Diagram: view it on warrendeleon.com

remoteLocator.test.ts walks this tree, including a chunk resolved by its caller rather than its id, the case that proves the resolver reads its second argument at all.

scriptManager.ts registers it at module scope, so it is in place before anything federated can be imported, whatever order the launch runs in: once webpack and the federation runtime have loaded a container or a chunk they never ask for it again, so a resolver added after a script's first load never sees that script.

ScriptManager.shared.addResolver(
  async (scriptId: string, caller?: string) => {
    const resolution = resolveRemoteLocator({
      scriptId,
      caller,
      remoteNames: REMOTE_NAMES,
      mode: status.mode,
      versions: status.versions,
      platform: Platform.OS,
      cdnBase: CDN_BASE,
      verify: VERIFY,
    });
    if (resolution.kind === 'refuse') {
      // Thrown, not returned. Returning nothing passes the script to the next resolver, which for a
      // remote is Re.Pack's own and would load it unverified. Re.Pack's resolveScript stops at the
      // first resolver that throws, so the load fails and the tab shows its error state.
      throw new Error(`[federation] refused ${scriptId}: ${resolution.reason}`);
    }
    return resolution.kind === 'locate' ? resolution.locator : undefined;
  },
  { key: '__signed_resolver__', priority: 100 },
);

The priority is the line that decides whether any of this runs. Re.Pack's ResolverPlugin registers a resolver of its own for each remote as it is registered, with a key and no priority, so it takes ScriptManager's default, which is 2 in 5.2.5's source; resolvers run highest first. Once the launch re-registers the remotes, that built-in resolver is rebuilt from the versioned manifest URL, but its locator carries no verification setting, so a custom resolver below 2 loses to it, and loses quietly: the right versions load, and every chunk loads unverified. 100 is far above 2, and scriptManager.test.ts asserts it against the stand-in.

The same built-in resolver is why returning nothing is unsafe when a remote has no version. Returning nothing hands the load to it, and it would fetch the script from the unversioned build-time URL with no signature check. Throwing ends the search instead, because Re.Pack's resolveScript stops at the first resolver that throws.

The map arrives over the network, so parseVersionMap reads it as a stranger's JSON. A version becomes a path segment in a URL the app downloads code from, so each one is checked against /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/ first: a slash would climb out of the version directory, and the leading character rules out ... One bad version refuses the whole map, because a half-read map would launch the app on versions nobody published; remote names this binary has never heard of are ignored, since one CDN can serve several apps. remoteLocator.test.ts covers the shapes the parser refuses and the names it ignores.

Turn the key

Post 14 signed every production chunk and read none of the signatures: "a signature nobody verifies is a stamp, not a lock." The lock is one field on the locator:

// --- Signature verification is only meaningful where there is a public key to verify against:
// the key is embedded in the iOS Info.plist and in Android's strings.xml, and nowhere else. On
// those two platforms it is strict, which means a chunk whose signature does not match the key,
// or which carries no signature at all, is rejected before it executes. ---
const SIGNED_PLATFORMS = ['ios', 'android'];
const VERIFY: VerifyMode = SIGNED_PLATFORMS.includes(Platform.OS) ? 'strict' : 'off';

Re.Pack accepts three values. lax verifies only when a token is present and lets an unsigned chunk through; off verifies nothing; strict refuses a mismatched signature and a missing one alike, which is what makes the stamp a lock.

Each platform reads the key by name: iOS from Info.plist under RepackPublicKey, Android from res/values/strings.xml under the same name. Both files are committed and compiled into the binary, so the generator you copied from the tag now writes the key into them.

The two platforms take it in different shapes. iOS parses PEM, the base64 text between BEGIN and END lines, so it gets the file as saved. Android uses only the base64 body, stripping those lines and the line breaks before it decodes, so it gets that body alone, on one line. Before building either shape, the generator turns Windows line endings (CRLF, a carriage return and a line feed) into Unix ones (LF), so a key saved by any editor embeds the same value. Its check against the private key compares DER, the binary form both shapes encode, so line endings cannot break it either:

// --- Put the public half where the app reads it. The two platforms take the key in two shapes:
// iOS parses PEM, so it gets the file verbatim; Android strips the header, the footer and the line
// breaks before it decodes, so it is given the base64 body alone, on one line. ---
// Line endings are normalised before either shape is built, so a public key that has been through
// a tool or an editor that writes CRLF embeds exactly the values one saved with LF does. It still
// matches its private key either way: the check above compares DER bytes, not text.
const publicPem = readFileSync(publicPath, 'utf8').replace(/\r\n/g, '\n').trim();
const publicBase64 = publicPem
  .split('\n')
  .filter(line => !line.includes('PUBLIC KEY'))
  .join('');

The rest of the generator's change replaces the value of an existing entry in each file. It treats a missing entry as an error rather than a warning, because strict verification fails closed: a key that never reached the app surfaces later as every remote refusing to load, with a message that says nothing about the generator. So add both entries now, empty, for the generator to fill. In apps/host/ios/Host/Info.plist, inside the top-level <dict> and above RCTNewArchEnabled:

<!-- The public half of the chunk-signing keypair. Re.Pack's native verifier reads it from
     this key by name, and strict verification fails closed without it. Written here by
     tools/gen-signing-keys.mjs; left empty in the repository because the key is generated per
     checkout, and a public key is safe to commit but a stale one is not useful. -->
<key>RepackPublicKey</key>
<string></string>

and in apps/host/android/app/src/main/res/values/strings.xml, after app_name:

<!-- The public half of the chunk-signing keypair, read by name by Re.Pack's native verifier.
     The base64 body alone, on one line: the verifier strips any PEM header, footer and line
     breaks before it decodes. Written by tools/gen-signing-keys.mjs; empty in the repository,
     because the key is generated per checkout. -->
<string name="RepackPublicKey"></string>

Run the generator. Post 14's private key is kept, and the public half lands in both files; the first three lines of its output say so:

node tools/gen-signing-keys.mjs

chunk-signing keypair already present, kept
embedded the public key -> apps/host/ios/Host/Info.plist
embedded the public key -> apps/host/android/app/src/main/res/values/strings.xml

Verification happens at download time. On both platforms the check runs inside the download-and-cache path, and a script already on disk is executed without being verified again. In this build that window is one session: the locator cache lives in memory (no setStorage), so every launch downloads and verifies every chunk afresh, and the server logs in this post show it. A build that persists that cache extends the window to the life of the cached file.

Two binaries, one CDN

The map is per app version, rather than one file for everyone, because compatibility cannot be negotiated on the device. The host's copy of each shared singleton is the one copy in the runtime, loaded before any remote, which is post 3's contract; a remote built against a different version cannot bring its own. So the choice is made on the server, per binary. Two builds from one checkout show it. Serve the tree, then build the Release scheme twice, once per app version, onto two simulators:

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release --udid <simulator A> )

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=1.0.0 npm run ios -- --mode Release --udid <simulator B> )

Both boot on the Pokédex tab with no dev server running. The 2.0.0 build's chip reads listApp 1.1.0 and its banner cdn · listApp 1.1.0 · partyApp 1.0.0; the 1.0.0 build's chip reads listApp 1.0.0. The server's terminal says why (trimmed for length: the vendor chunks, the party's chunks and the 1.0.0 launch's lines after its container are cut):

[2026-09-21T15:51:21.029Z]  "GET /ios/maps/2.0.0/version-map.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:51:21.069Z]  "GET /ios/listApp/1.1.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:51:21.076Z]  "GET /ios/partyApp/1.0.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:51:21.083Z]  "GET /ios/listApp/1.1.0/listApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:51:21.095Z]  "GET /ios/partyApp/1.0.0/partyApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:51:21.152Z]  "GET /ios/listApp/1.1.0/__federation_expose_ListStack.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:53:56.057Z]  "GET /ios/maps/1.0.0/version-map.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:53:56.091Z]  "GET /ios/listApp/1.0.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:53:56.116Z]  "GET /ios/listApp/1.0.0/listApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"

The map first, then the manifests, then every chunk inside the directory the map named. Same CDN, two binaries, two answers. The skews this arrangement handles:

Situation	What changes on the CDN	What each installed binary loads
A fix to a remote, for everyone	A new version directory, then the line in every map that should take it	Its own map's version, at its next launch
A remote that needs a newer shared singleton	A new version directory, and a line in the new app version's map only	Old binaries keep their old line; the new binary gets the new version once it ships
A host release with no remote change	A new map, copied from the last one	The same remote versions the last app version ran
A bad version already shipped	The map line put back	The previous version, at the next launch, with nothing rebuilt

The detail screen has no row because it is not a remote of its own. Since post 5 it has been a package compiled into whichever remote installs it, so a detail fix ships as a new version of the list and of the party. The unit of a flip is the remote, and everything installed into it moves with it.

Android needs one more declaration: MF_APP_VERSION joins MF_CDN_BASE as an input of the bundle task, for the reason post 14 gave, and the block post 14 added to apps/host/android/app/build.gradle becomes:

// --- MF_CDN_BASE and MF_APP_VERSION are read by rspack.config.mjs when the bundle task runs, and
// Gradle cannot see that: an environment variable is not one of the task's declared inputs, so a
// build where only the value changed leaves createBundleReleaseJsAndAssets UP-TO-DATE and ships
// the previous bundle, dev-server URLs and all. Declaring them as inputs makes a changed value
// rebuild the bundle and an unchanged one keep the cache.
//
// MF_APP_VERSION matters here for the same reason, and more: the two-binaries demo, run on
// Android, builds the same source twice with nothing different but that variable, so without this
// line the second build silently ships the first one's bundle and asks the CDN the first one's
// question. ---
tasks.configureEach {
    if (name.startsWith("createBundle") && name.endsWith("JsAndAssets")) {
        inputs.property("MF_CDN_BASE", System.getenv("MF_CDN_BASE") ?: "")
        inputs.property("MF_APP_VERSION", System.getenv("MF_APP_VERSION") ?: "")
    }
}

node tools/build-cdn.mjs android && ( cd apps/host && MF_CDN_BASE=http://10.0.2.2:8000 MF_APP_VERSION=2.0.0 npm run android -- --mode release )

Ship 1.2.0

The installed 2.0.0 app shows list 1.1.0. Ship it a change a user would see: when the party reaches six members, the counter in the Pokédex header changes its label from "My Party" to "Party full", and its pill deepens. In PokedexScreen.tsx, after partyCount:

const partyFull = partyCount >= MAX_PARTY;

The counter group reads it three times: for the visible label, for the label a screen reader speaks, and for the pill's fill. Its comments say why the full state is marked by the word and by the colour:

{/* The count changes when the user adds a member from a screen away, without focus
    moving here. A sighted user sees the number tick; a screen-reader user is told
    nothing unless this is a live region (SC 4.1.3). The label spells the ratio out,
    because "3/6" is read as "three slash six" or as a date, depending on the reader.
    At six it reads the full state too, which is the word a colour alone cannot say. */}
<Box
  className="flex-row items-center gap-2"
  accessible
  accessibilityLiveRegion="polite"
  accessibilityLabel={`${partyFull ? 'Party full' : 'My Party'}, ${partyCount} of ${MAX_PARTY}`}>
  <Text size="sm" className="font-semi text-darkGrey dark:text-lightGrey">
    {partyFull ? 'Party full' : 'My Party'}
  </Text>
  {/* Full is the party's one state worth marking, and it is marked twice: the label
      beside this pill changes, and the pill deepens. The label carries the state for
      everyone, including anyone who cannot use colour (SC 1.4.1); the deeper pill
      makes it visible at a glance, in both themes.
      The dark half deepens by alpha rather than by hue, because the pill over navy is
      translucent white in the first place and a green fill there would be a different
      component wearing the same shape.
      darkGrey, not darkGreen: darkGreen is #A6D3A0, the grass fill, and on lightGreen
      it measures 1.53:1. darkGrey is the colour the label beside it already uses, and
      it clears the bar on both greens. All four pairs are in the contrast matrix. */}
  <Box
    className={`rounded-full px-2.5 py-0.5 ${
      partyFull ? 'bg-pokemonGreen dark:bg-white/20' : 'bg-lightGreen dark:bg-white/10'
    }`}>
    <Text size="xs" className="font-head text-darkGrey dark:text-pokemonGreen">
      {partyCount}/{MAX_PARTY}
    </Text>
  </Box>
</Box>

Every pair this post paints is measured in the contrast matrix post 12 built; the four new rows are in the design-system test you copied. The list's own accessibility tests check the full state's label and its pill, in both themes, and the chip beside them; copy them from the tag now:

cp /tmp/pokedex-ref-15/apps/list/__tests__/ListStack.accessibility.tsx apps/list/__tests__/

Now build the change as a version and put its directory on the CDN. Not through build-cdn, which seeds a tree from its lists and would rewrite everything the server is serving: the operation is two commands against the tree already there.

( cd apps/list && MF_REMOTE_VERSION=1.2.0 npm run bundle:ios:prod ) && rsync -a --exclude '*.map' --exclude mf-stats.json apps/list/cdn/ios/listApp/1.2.0/ cdn-root/ios/listApp/1.2.0/

Nothing has changed for anybody. The directory is there and no map points at it. Then the second step, one line of cdn-root/ios/maps/2.0.0/version-map.json:

{
  "listApp": "1.2.0",
  "partyApp": "1.0.0"
}

Relaunch the installed 2.0.0 app. Nothing was rebuilt and nothing was reinstalled. A phone takes the change the same way, at its next launch, and a user who already has the app open keeps the code they loaded until then. The server's log, with the list's vendor chunk lines cut for length:

[2026-09-21T15:52:00.957Z]  "GET /ios/maps/2.0.0/version-map.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:00.977Z]  "GET /ios/listApp/1.2.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:00.981Z]  "GET /ios/partyApp/1.0.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:00.987Z]  "GET /ios/listApp/1.2.0/listApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:00.995Z]  "GET /ios/partyApp/1.0.0/partyApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:01.038Z]  "GET /ios/listApp/1.2.0/__federation_expose_ListStack.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:01.185Z]  "GET /ios/partyApp/1.0.0/__federation_expose_styles.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:52:01.185Z]  "GET /ios/partyApp/1.0.0/__federation_expose_partySlice.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"

The chip reads listApp 1.2.0, the banner agrees, and with six Pokémon added the header says Party full on a deeper pill. The 1.0.0 binary on the other simulator, launched after the flip, still loaded listApp 1.0.0: its own map never changed.

🎞️ Animated demo: watch it on warrendeleon.com

Upload the version directory first. Flip the map last. The map is the commit. Nothing in this build gives a binary anywhere else to load a remote from, so a map that points at a directory not yet on the CDN is a 404 for every user who launches in between, and what they get is a tab that will not open. The missing-version break-it in Now break it, three times is what the other order looks like.

Record the release in the tool too, so its lists match what the CDN now holds. In tools/build-cdn.mjs the two lists and their comments become:

// --- Every version of each remote the CDN holds. A version directory is written once and then
// left alone: installed apps are loading those exact files, so a rebuild of a published version
// is a silent change to code somebody is already running. New work gets a new number.
//
// listApp has three because this post ships two releases of it. 1.0.0 and 1.1.0 are the same
// screen with different stamps on it, which is what the two-binaries demo needs; 1.2.0 is the
// build that added the party counter's full state, and it is the one the flip ships. This tool
// builds every version from the source in front of it, so rebuilt from the finished tree all three
// carry that state: the post builds 1.0.0 and 1.1.0 before making the change, which is what keeps
// them without it. ---
const REMOTE_VERSIONS = {
  listApp: ['1.0.0', '1.1.0', '1.2.0'],
  partyApp: ['1.0.0'],
};

// --- What each released app version may load. The host asks for its own entry by name at every
// launch, so an old binary keeps being handed the versions it was built against, however far the
// newest release has moved on. An entry is retired when nobody is left on that app version, the
// same way an old API endpoint is.
//
// 2.0.0 pointed at listApp 1.1.0 until the flip; the line below is what changed, and changing it
// back is the rollback. Editing it here rebuilds the whole tree, which is the wrong tool for that
// job: the operation the post performs is an edit to the map file already sitting in cdn-root,
// because that file is what a running app reads. This is the seeding of a CDN, not an operation
// against one.
//
// There is nothing else in the map. No signature over it, no counter, nothing that would let the
// app tell a map written here from one written by anybody else who can reach the bucket. That is
// a real hole and it is left open on purpose: it is the subject of the last post in the series. ---
const APP_VERSION_MAPS = {
  '1.0.0': { listApp: '1.0.0', partyApp: '1.0.0' },
  '2.0.0': { listApp: '1.2.0', partyApp: '1.0.0' },
};

That edit is bookkeeping; the deploy already happened. It also means a fresh seeding from the finished tree builds all three versions from one source, so 1.0.0 and 1.1.0 would carry the full-party state too: the order you just followed is what keeps them without it.

Two caching rules make the operation safe to repeat. Each chunk URL includes its version, so the CDN, a proxy or the device can keep that file forever without confusing it with a later release. The version map changes with every deploy, so it gets the opposite rule: the probe sends cache-control: no-cache, and locally -c-1 makes http-server send cache-control: no-cache, no-store, must-revalidate. A production CDN gets the same two rules as configuration.

This host still downloads the party's unchanged 1.0.0 chunks after a relaunch, as the log shows, because it keeps the locator cache in memory only. Persisting that cache would save those downloads, and would also extend how long a file on disk runs without another signature check, for the reason in the "Verification happens at download time" callout.

Roll it back

The version that shipped is wrong. Put the line back:

{
  "listApp": "1.1.0",
  "partyApp": "1.0.0"
}

Relaunch, and the log moves back to 1.1.0 with nothing rebuilt, because the old directory was never removed. The two lists in build-cdn make this possible: the CDN keeps 1.1.0 while nothing points at it, so a rollback is an edit and never a build.

The same plain file that makes rollback a one-line edit lets anyone who can write to the bucket steer every installed app to whichever version they choose, including an old one with a known fault. The chunks are guarded; the map is naked. Post 17 is about that file.

Now break it, three times

A refused chunk and a missing version look the same on the screen and mean opposite things. A release whose module throws while it initialises looks no different. Run all three on the Release build, with the map pointing at 1.2.0 again.

First, the system working. Change one byte inside the exposed chunk on the CDN and relaunch:

printf 'X' | dd of=cdn-root/ios/listApp/1.2.0/__federation_expose_ListStack.chunk.bundle bs=1 seek=2000 conv=notrunc

The server serves the chunk, the device downloads it, and verification refuses it before a line of it runs. A Release build has no Metro console, so read the simulator's own log:

xcrun simctl spawn <simulator A> log show --last 1m --predicate 'process == "Host"' --style compact | grep -A17 'Failed to load script'

The match and the lines that matter in the seventeen after it, with the log's own prefix cut:

'[ScriptManager] Failed to load script:', '[ScriptDownloadFailure]', { scriptId: '__federation_expose_ListStack',
  caller: 'listApp',
     url: 'http://localhost:8000/ios/listApp/1.2.0/__federation_expose_ListStack.chunk.bundle',
   { [Error: The bundle verification failed because the bundle hash is invalid.]
     code: 'ScriptDownloadFailure',

The Pokédex tab shows the design system's error state, "This tab could not load" with a Try again button; the banner still reads cdn · listApp 1.2.0 · partyApp 1.0.0; the Party tab opens and works. The line under the title follows the launch's mode: from the CDN it says the remote could not be downloaded, verified or started and suggests a relaunch, where post 11's wording pointed at a dev server this build does not have.

Append bytes after the end of the file instead and the logged error becomes no token for the bundle was found: the verifier reads the file's last 1,280 bytes and expects them to begin with the signature's marker, and the appended bytes moved that window past it. Strict mode refuses that too. Restore the chunk from the built copy before going on.

Second, the operational failure. Point the 2.0.0 map at a version whose directory does not exist, 1.3.0, and relaunch:

[2026-09-21T15:54:25.541Z]  "GET /ios/listApp/1.3.0/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-21T15:54:25.542Z]  "GET /ios/listApp/1.3.0/mf-manifest.json" Error (404): "Not found"

The same error state on the same tab, and the banner reports listApp 1.3.0, the version it was told to load. Nothing was tampered with; the map was written before the directory it names, which is the wrong order the "map is the commit" callout warns about, seen from the user's side. Copy any built version into cdn-root/ios/listApp/1.3.0/ and the next launch loads it. Put the map back to 1.2.0.

Third, a release with a bug in it. Add one line below the imports of apps/list/src/PokedexScreen.tsx:

throw new Error('PokedexScreen failed to initialise');

Ship it the way 1.2.0 shipped, as a version of its own, then point the 2.0.0 map at 1.4.0:

( cd apps/list && MF_REMOTE_VERSION=1.4.0 npm run bundle:ios:prod ) && rsync -a --exclude '*.map' --exclude mf-stats.json apps/list/cdn/ios/listApp/1.4.0/ cdn-root/ios/listApp/1.4.0/

The requested JavaScript bundles download and pass signature verification, but the tab shows the same error state again, with the banner reporting listApp 1.4.0. Nothing failed to load this time: the list's code arrived intact and threw while its module initialised. Delete the line and put the map back to 1.2.0.

None of the three error states appeared the first time its failure ran on an iOS Release build: the app died before any of them could be drawn. Android had already shown the same death in post 14, where a release build's refused manifest request ended the boot.

For the first two, the cause is the order in which the failure is reported. When a remote's module fails to load, webpack's remote runtime records the error, appends while loading "./ListStack" from … to its message, and replaces the module's factory with one that throws. Re.Pack replaces webpack's require with a guarded version in every bundle it builds: when a require throws, the guard catches the error, reports it to React Native's global error handler as fatal, and returns nothing. That report comes first, before React has tried to render the tab.

In a development build the fatal report is a red box over a working app. In a Release build the handler passes it to React Native's native error handling, where the fatal path ends the process: on iOS the exceptions module calls RCTFatal, which throws an exception nothing catches, and on Android it throws a JavascriptException that the default host rethrows.

If the process survives that report, the tab still reaches its error state. The guarded require's empty return lets the tab's import settle without a component, React refuses to render it (Element type is invalid), and RemoteBoundary, which post 11 put around each tab, catches that render error and shows the error state. The boundary never sees the original loading error; it handles the failure that follows from it.

src/shell/federationErrors.ts lets the process survive. It wraps React Native's global handler and, for the first two breaks, drops the report whose message ends with the suffix the remote runtime appended, which the runtime writes at exactly one place and always as the message's last line:

const HANDLED_BY_REMOTE_RUNTIME = /\nwhile loading "[^"\n]+" from \S+$/;

export function isHandledRemoteLoadError(error: unknown): boolean {
  if (typeof error !== 'object' || error === null) {
    return false;
  }
  const { message } = error as { message?: unknown };
  return typeof message === 'string' && HANDLED_BY_REMOTE_RUNTIME.test(message);
}

Two earlier versions of that matcher were written, measured and removed, and both are now test cases. The first matched ChunkLoadError by name and also required the container half of the suffix to name the remote. In a development build that half reads webpack/container/reference/listApp; in a Release build that module is minified to its numeric id, 77469, so the check passed in development and failed exactly where it mattered. The second dropped the container check but still matched ChunkLoadError by name, which is what a bad signature arrives as; a version the CDN does not hold arrives as [ Federation Runtime ]: Failed to get manifest. #RUNTIME-003 with the same suffix, and it still killed the app. For a failed load, the guard matches the suffix alone.

The suffix covers the first two breaks and not the third. The list's code downloaded and verified, then threw while its module was being evaluated. The remote's container is a bundle Re.Pack built too, so the outermost require inside it is guarded as well, and it reports the throw as fatal before anything returns. The remote runtime saw a successful load, so nothing appended a suffix, and with the matcher alone the Release build died at launch:

*** Terminating app due to uncaught exception 'RCTFatalException: Unhandled JS Exception: Error: PokedexScreen failed to initialise'

The guard can recognise the third break's report by its timing instead: it arrives while a remote module is being evaluated. When the host imports a remote module, the remote runtime asks Module Federation for the module's factory unexecuted, with loadFactory: false, and Module Federation passes that factory to every runtime plugin's onLoad hook before anything calls it. A function returned from the hook replaces the factory. src/shell/scriptManager.ts installs a plugin that returns one running the real factory inside evaluateRemoteModule, so every remote module the host imports, for the tabs and at boot, is evaluated there:

const evaluationWindow: ModuleFederationRuntimePlugin = {
  name: 'evaluation-window',
  onLoad({ exposeModuleFactory }) {
    if (typeof exposeModuleFactory !== 'function') {
      return undefined;
    }
    return () => evaluateRemoteModule(exposeModuleFactory);
  },
};
registerPlugins([evaluationWindow]);

evaluateRemoteModule, in federationErrors.ts, opens a window around the factory. Any fatal report raised while the window is open comes from evaluating that module, so the guard holds it instead of passing it on. Once the factory returns, evaluateRemoteModule throws the held error:

export function evaluateRemoteModule<T>(factory: () => T): T {
  const globals = store();
  const outer = globals[EVALUATING];
  const evaluation: Evaluation = {};
  globals[EVALUATING] = evaluation;
  try {
    let exports: T;
    try {
      exports = factory();
    } catch (error) {
      throw remember(error);
    }
    if (evaluation.failure) {
      throw remember(evaluation.failure.error);
    }
    return exports;
  } finally {
    globals[EVALUATING] = outer;
  }
}

The window is exact because evaluation is synchronous: nothing else runs between opening it and closing it. Only fatal reports are held, because only a fatal report ends the process.

The error thrown from the window then reaches the host's own guarded require, which reports it as fatal a second time, outside the window. remember keeps every error thrown from the window, and the guard drops that second report the way it drops one that ends with the suffix. The import settles without the module, and the tab reaches the same error state as the other two breaks.

The installed guard puts the two paths together. It holds a fatal report raised inside a window, drops a report that ends with the suffix or repeats an error thrown from a window, and passes everything else to the handler that was there before:

// --- Where the guard keeps the handler it wraps. Fast Refresh can evaluate this module again in a
// running app, and each evaluation starts with fresh module state, so a flag in this file cannot
// tell a second installation from a first. The wrapper carries the handler underneath it instead,
// on a property every evaluation of the module knows by name. ---
const WRAPPED = '__federationGuardWrapped';
type GuardHandler = GlobalErrorHandler & { [WRAPPED]?: GlobalErrorHandler };

export function guardHandledRemoteLoadErrors(): void {
  const errorUtils = (globalThis as { ErrorUtils?: ErrorUtilsShape }).ErrorUtils;
  if (!errorUtils) {
    return;
  }
  const current: GuardHandler = errorUtils.getGlobalHandler();
  const previous = current[WRAPPED] ?? current;
  const guard: GuardHandler = (error, isFatal) => {
    const evaluation = store()[EVALUATING] as Evaluation | undefined;
    if (evaluation && isFatal) {
      evaluation.failure ??= { error };
      console.warn(
        '[federation] a remote module threw while it was evaluated; the import that asked for it settles without it',
        error,
      );
      return;
    }
    if (isHandledRemoteLoadError(error) || isThrownFromEvaluation(error)) {
      // Logged, not swallowed: the reason behind a tab's error state belongs in the console of
      // whoever is looking at it.
      console.warn(
        '[federation] a remote failed to load; its tab will show the error state',
        error,
      );
      return;
    }
    previous(error, isFatal);
  };
  guard[WRAPPED] = previous;
  errorUtils.setGlobalHandler(guard);
}

Installing the guard again replaces the one it finds rather than wrapping it. Fast Refresh can run the module again during development, and a second wrapper would leave the first one's checks running underneath; federationErrors.test.ts re-evaluates the module to hold it to one guard. The window and the record remember keeps are stored on the global object for the same reason, so every evaluation of the module shares them.

None of this gives the binary anywhere else to load from: a dead tab is honest, and it is not a working app.

What the stores permit

Everything in this post downloads code into an installed app, so the platform rules apply, and both vendors have reworded these clauses before. Every quotation in this section comes from the current pages.

Platform	Governing text	What it says	Condition
Apple, review	App Review Guideline 2.5.2	Apps may not "download, install, or execute code which introduces or changes features or functionality of the app, including other apps"	The reviewed binary is what the app does; downloaded code may not add to or change that
Apple, licence	Developer Program License Agreement 3.3.1(B)	"Interpreted code may be downloaded to an Application but only so long as" three conditions hold	It keeps the app's intended and advertised purpose; it does not bypass the operating system's signing, sandbox or other security features; in an App Store app, it creates no store or storefront for other apps
Google Play	Device and Network Abuse policy	An app "may not download executable code (such as dex, JAR, .so files) from a source other than Google Play"	The restriction "does not apply to code that runs in a virtual machine or an interpreter where either provides indirect access to Android APIs"

Apple's two documents draw different lines, and both apply. The licence agreement's clause 3.3.1(B) permits downloaded interpreted code only so long as it "does not change the primary purpose of the Application by providing features or functionality that are inconsistent with the intended and advertised purpose of the Application", "does not bypass signing, sandbox, or other security features of the OS", and, "for Applications distributed on the App Store, does not create a store or storefront for other Applications". Guideline 2.5.2 is stricter: the licence's first condition protects the app's purpose, while the guideline rules out downloaded code that introduces or changes the app's features or functionality. So meeting the licence's conditions does not establish compliance with review. The reading over-the-air services operate on is to keep what ships this way to fixes and adjustments within the functionality Apple already reviewed, accepting that the wording leaves Apple room to disagree.

Google's rule names an exception rather than a condition: the restriction "does not apply to code that runs in a virtual machine or an interpreter where either provides indirect access to Android APIs (such as JavaScript in a webview or browser)". The policy does not name React Native or Hermes (the JavaScript engine React Native runs by default), so whether Hermes fits is an inference. It is a sound one: JavaScript under Hermes reaches Android APIs only through the natively compiled modules the binary already contains, which is indirect access in the clause's own terms. The chunks on this CDN are plain JavaScript rather than Hermes bytecode, because no remote in the series compiles to bytecode; the policy's line is about how code runs, not the form it ships in. The same page adds that interpreted code "loaded at run time (for example, not packaged with the app) must not allow potential violations of Google Play policies", so what a remote does is held to the same rules as the app it runs in.

For React Native in particular, the closest guidance comes from the vendors who ship over-the-air updates for it. Microsoft's CodePush served that market for years and was retired on 31 March 2025. EAS Update, the over-the-air service in Expo Application Services, still runs, and its documentation holds updates to the stores' rules: "you need to follow the rules of the platforms and app stores you are building for", updates "need to follow the App Store and Play Store guidelines, including the content of the updates and how you use them", and "This usually means changes to your app's behavior need to be reviewed". Its table of when to use an update marks "Change to native code or native dependencies" and "Anything that requires a new app binary version" as cases for a new binary instead.

The practical rule: ship fixes and improvements to features the store already reviewed, never a new primary purpose, and keep the reviewed binary able to work on its own. The flip in this post is the kind of change the first half describes: it changes how an existing feature, the party counter, shows a state, and adds nothing new. Whether a particular change stays inside what was reviewed is the store's judgement, and no build can establish it. The second half needs the copy in the binary that post 16 adds, because today a binary that cannot reach the CDN has nothing to show.

Run it

Keys, tree, server:

node tools/gen-signing-keys.mjs && node tools/build-cdn.mjs ios

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

The Release build, told where the CDN is and which binary it is:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm run ios -- --mode Release )

A development build works the same way, with the two variables on the dev server's command instead:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 MF_APP_VERSION=2.0.0 npm start )

( cd apps/host && npm run ios )

Android, with the emulator's address for the machine:

node tools/build-cdn.mjs android && ( cd apps/host && MF_CDN_BASE=http://10.0.2.2:8000 MF_APP_VERSION=2.0.0 npm run android -- --mode release )

The suites, the smoke test and the generator's tests:

( for d in apps/host apps/list apps/party packages/ui; do ( cd "$d" && npx jest --silent ) || exit 1; done ) && sh scripts/federation-smoke.sh && node --test tools/gen-signing-keys.test.mjs

The smoke test now builds both remotes at 9.9.9, a version no config defaults to, and follows the manifest's own chunk list into the version directory, so a version segment missing from output.path fails at build time rather than at a user's launch.

Run from the finished tree, build-cdn builds all three list versions from the same source and seeds the 2.0.0 map with 1.2.0, so the three versions differ only in the chip. To watch a flip here, edit cdn-root/ios/maps/2.0.0/version-map.json to name listApp 1.1.0 and relaunch, then put 1.2.0 back and relaunch again. The full-party state arriving with the flip belongs to the build-along, the only route that builds 1.0.0 and 1.1.0 before the change.

What you built, and what's next

An installed binary now asks the CDN for its own map at launch, loads the signed versions that map names, and refuses any remote the map gives no version. Shipping a remote is one directory and one line, and a rollback is the line put back; each binary takes either at its next launch. When a remote fails to load, or its module throws while it initialises, the Release build keeps running with one dead tab: measured on iOS with a refused chunk, a missing version and a module that throws as it initialises, and on Android with a missing version.

Two limits remain. The map is unsigned, so anyone who can write to the bucket can steer every install; post 17 signs it, adds a counter that makes yesterday's map worthless, and has the app roll a failing version back on its own. The nearer limit is reach: a binary that cannot reach the CDN, or cannot read its map, launches in unresolved mode with nothing to show in either tab.

Next: the day the CDN is unreachable. An offline fallback baked into the binary, and an in-session net for the remote that fails mid-use.

Sources

Module Federation: runtime hooks — onLoad, the hook that receives a remote module's factory before anything calls it when that factory was requested with loadFactory: false
Module Federation: runtime API — registerRemotes and its force option: an already-registered module is overwritten and its cache deleted, and a warning says the operation is risky
Module Federation source: runtime-core remote/index.ts at 2.9.0 — the branch for an already-registered name, which does nothing without force and warns with it, and loadRemote, which passes the onLoad hook a factory nothing has run when loadFactory is false, and returns a function the hook hands back in its place
Module Federation source: webpack-bundler-runtime remotes.ts at 2.9.0 — the error handler that appends while loading "…" from … and replaces the failed module with one that throws, and the request for each remote module's factory with loadFactory: false
Module Federation source: runtime-core module/index.ts at 2.9.0 — get, which runs a module's factory before returning unless loadFactory is false
Re.Pack: ScriptManager — addResolver with its priority and key options, the default priority of 2, and verifyScriptSignature
Re.Pack: CodeSigningPlugin — the plugin post 14 configured and this post verifies against
Re.Pack source: ScriptManager.ts at 5.2.5 — DEFAULT_RESOLVER_PRIORITY = 2, resolvers sorted highest first, resolveScript asking the next resolver whenever one returns nothing and stopping when one throws, and the in-memory locator cache
Re.Pack source: ResolverPlugin.ts at 5.2.5 — the per-remote resolver registered with a key and no priority
Re.Pack source: OutputPlugin.ts at 5.2.5 — remote chunks copied to extraChunks.outputPath from where Rspack wrote them, not moved
Re.Pack source: guardedRequire.ts at 5.2.5 — the require Re.Pack builds into every bundle, which catches a module that throws, reports the error to ErrorUtils as fatal and returns nothing
Re.Pack source: ScriptManager types at 5.2.5 — verifyScriptSignature as 'strict' | 'lax' | 'off', and what cache compares
Re.Pack source: ScriptManager.mm at 5.2.5 — verification inside the iOS download path, for strict always and for lax only when a token is present
Re.Pack source: RemoteScriptLoader.kt at 5.2.5 — the same check on Android, and a cached file executed without it
Re.Pack source: CodeSigningErrors.swift, CodeSigningUtils.swift and CodeSigningUtils.kt at 5.2.5 — the verification failures quoted in this post, the token read from the last 1,280 bytes, and RepackPublicKey read from Info.plist and from strings.xml
React Native source: setUpXHR.js at 0.85.3 — AbortController and AbortSignal installed from the abort-controller package, which has no timeout
React Native source: error-guard.js at 0.85.3 — ErrorUtils.reportFatalError, which calls the global handler with its fatal flag set, and setGlobalHandler and getGlobalHandler
React Native source: ExceptionsManager.js at 0.85.3 — LogBox in development; otherwise the error handed to the native error handler, which the new architecture installs
React Native source: RCTInstance.mm and RCTExceptionsManager.mm at 0.85.3 — an error no host delegate claims forwarded to the exceptions module, whose fatal path calls RCTFatal
React Native source: RCTAssert.m at 0.85.3 — RCTFatal throwing an exception that only a debug build catches
React Native source: ExceptionsManagerModule.kt at 0.85.3 — a fatal report thrown as a JavascriptException
React Native source: ReactInstance.kt and DefaultReactHost.kt at 0.85.3 — that throw routed to the host's exception handler, which rethrows by default
App Store Review Guidelines, 2.5.2 — the self-contained-apps constraint, quoted from the current text
Apple Developer Program License Agreement, 3.3.1(B) — the interpreted-code permission and its three conditions, quoted from the public copy
Google Play: Device and Network Abuse policy — the executable-code restriction, its interpreter exception and its rule for interpreted code loaded at run time, quoted from the current text
Expo: EAS Update introduction — the answer on store guidelines and the table of when to use an update, quoted from the current page
microsoft/react-native-code-push — the archived repository, with its notice that CodePush was retired on 31 March 2025
http-server — the -c option, where -c-1 disables caching
react-native-module-federation — the companion repo, the build at the tag post-15-cdn-flip

The production build and the three modes of a federated React Native app

Warren de Leon — Mon, 05 Oct 2026 00:03:42 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 13 ended on a promise: "the build gets real: a production bundle, and the first federated release artefact." This is that post. The larger promise is post 1's, that each feature "can be deployed and updated on its own instead of riding in a single App Store release", and the same post listed the price: a CDN to run, a URL that is an attack surface, code to sign and to verify. Thirteen posts in, both remotes still arrive from two dev servers on your machine. This post builds them for production, signs every chunk, and serves them from a content delivery network (CDN) with those dev servers switched off.

The honest scope first. The CDN in this post is a directory and a port, holding one version of each remote, with nothing yet that verifies a signature, guards the choice of version, or falls back when the CDN is unreachable. The next three posts add all of that, and each of them handles the artefacts this one produces.

Start from post 13's finished state, the start tag post-13-native-handoff. The end tag is post-14-production-build, and everything between the two you type.

📊 Diagram: view it on warrendeleon.com

Three channels, three cadences. The registry's arrow ends at node_modules and never reaches the running app: a package change ships inside the next build of whoever installs it. A remote change lands on the CDN and reaches the app at its next launch. A host change goes through the store.

Three modes, one table

The series has lived in the first row since post 2 and used the second since post 5, without naming either. Named, with the third beside them:

Channel	What it serves	Who reads it, and when	What a change costs
Dev servers, `:8082` and `:8083`	A remote's manifest, container and chunks, rebuilt on every save	The host app, at runtime, whenever `MF_CDN_BASE` is unset: development builds, in practice	A save
Registry, Verdaccio on `:4873`	npm packages: `@pokedex/contracts`, `detail`, `ui` and `a11y-testing`	`npm install`, at build time, in every app that depends on the package	A publish, then a reinstall and a rebuild of each consumer
CDN, `cdn-root/` on `:8000`	A remote's manifest, container and chunks, built once and signed	The host app, at runtime, development or release build	A rebuild of the remote and a copy; every installed app picks it up at its next launch

The question the table exists to answer is the one most teams ask first: which changes still cost an app-store release? Anything the binary carries: native code, the host shell, and every shared singleton the host provides, because the host's bundle is where the one copy of each lives. Anything a remote owns costs a CDN deploy and a launch. Packages sit between the two, and the middle row is the one to read twice.

A registry is where versioned artefacts usually live, so it is a reasonable place to expect the remotes, and it is where a team new to federation tends to put them first. It does not hold them: the registry serves packages, never remotes. A package reaches users inside whichever bundle compiles it in.

Post 12 shipped @pokedex/detail 4.0.12 as a publish and a reinstall in list and party; under this post's modes that same fix is two rebuilt remotes on the CDN and no store release, because the host never bundles the detail package. A fix to @pokedex/contracts or @pokedex/ui is different. The host provides both as eager singletons, so the host bundle changes, and the host bundle ships in the binary.

Build a remote for real

Every bundle the series has run was a development build, served on save. A production build is the same command with the development switch off, and each remote gets it as two scripts. In apps/list/package.json:

"bundle:ios:prod": "react-native bundle --platform ios --dev false --entry-file src/index.js --config rspack.config.mjs",
"bundle:android:prod": "react-native bundle --platform android --dev false --entry-file src/index.js --config rspack.config.mjs",

The same two go in apps/party/package.json. react-native bundle reaches Re.Pack because post 2's react-native.config.js registered its commands with the CLI (webpack-bundle is an alias). --entry-file src/index.js names the container entry post 2 gave each remote; the template's index.js beside it registers the remote as a standalone app, which the CDN never serves.

The config gains one boolean and reads it in two places that have to agree: where the compilation writes, and where the chunks the host will fetch are laid out. In apps/list/rspack.config.mjs, after const { mode, platform } = env;:

// Production builds write somewhere else and gain a signature; development is untouched.
const isProd = mode === 'production';

output: {
  // A production build writes the tree the CDN serves, laid out as the URL path it is served
  // at: cdn/<platform>/listApp/. A development build keeps writing to build/, where the dev
  // server reads it from.
  path: isProd ? `${__dirname}/cdn/[platform]/listApp` : `${__dirname}/build/[platform]`,
  uniqueName: 'ListApp',
},

A third block has nothing to do with federation and everything to do with trusting a green build. Re.Pack's default minimiser is terser-webpack-plugin, and under Rspack that plugin has done nothing since its 5.6.0 release (callstack/repack#1390): the build reports success and every production chunk keeps its comments and whitespace. Name Rspack's own SWC minimiser beside it. Re.Pack merges your optimization.minimizer into its own list rather than replacing it, so the default stays in the array and goes on doing nothing while the SWC one does the minifying. Add the import at the top of the file:

import { SwcJsMinimizerRspackPlugin } from '@rspack/core';

and, after output:

optimization: {
  // Re.Pack's default minimiser is terser-webpack-plugin, and under Rspack that plugin has done
  // nothing since terser-webpack-plugin 5.6.0 (callstack/repack#1390): the build succeeds and
  // every production chunk ships with its comments and whitespace intact. Re.Pack merges this
  // array into its own, so the default still sits in the list beside Rspack's SWC minimiser;
  // the SWC one does the minifying the default skips.
  minimizer: [
    new SwcJsMinimizerRspackPlugin({
      test: /\.(js)?bundle(\?.*)?$/i,
      minimizerOptions: { format: { comments: false } },
    }),
  ],
},

The host gets the same import and block in apps/host/rspack.config.mjs, because its release bundle is built the same way. Then, still in the remote's config, the chunks:

new Repack.RepackPlugin({
  extraChunks: [
    {
      include: /.*/,
      type: 'remote',
      // The chunks land beside the container and the manifest, because the host will ask
      // for them at URLs relative to the manifest it loaded.
      outputPath: isProd ? `cdn/${platform}/listApp` : `build/${platform}/remote`,
    },
  ],
}),

Mirror all of it in apps/party/rspack.config.mjs with partyApp. Both output trees are build products, so they join .gitignore next to apps/*/build/:

apps/*/cdn/
cdn-root/

Then build one and look at what comes out:

( cd apps/list && npm run bundle:ios:prod ) && ls apps/list/cdn/ios/listApp | grep -v '\.map$' | head -6

assets
__federation_expose_ListStack.chunk.bundle
index.bundle
listApp.container.js.bundle
mf-manifest.json
mf-stats.json

Sixteen more chunks follow, most of them the remote's own copies of the shared singletons: fallbacks the host never requests, because it provides every one. The server log later in this post shows the few it does ask for. Three files matter here. The container is what the host loads first; the exposed chunk carries ./ListStack; and mf-manifest.json is the address book, emitted by default alongside its mf-stats.json twin. One field in it looks wrong on purpose:

"publicPath": "noop:///"

Re.Pack's base config sets it, and nothing treats it as a location. The host fetched the manifest from a URL, and Re.Pack's resolver plugin rebases every chunk URL for that remote onto it, so each chunk is fetched from the directory the manifest came from. Where a remote was built has no bearing on where it is served, which is what lets one build move from a laptop to a real CDN unchanged.

One script assembles the tree a CDN would serve. Create tools/build-cdn.mjs:

// --- Assembles the directory a CDN would serve. For each remote it runs that remote's production
// bundle script, then copies the output — container, chunks and mf-manifest.json — into
// cdn-root/<platform>/<remote>/. That layout is the URL layout: a file at
// cdn-root/ios/listApp/mf-manifest.json is served at <base>/ios/listApp/mf-manifest.json, which is
// exactly the URL the host's remotes map asks for.
//
// One version of each remote lives here, in one flat directory. Versioned releases, and the map
// that decides which version a given app may load, arrive in the next post.
//
// Usage: node tools/build-cdn.mjs [ios|android]     (no argument builds both)
//
// Then serve it and point the host at it (an Android emulator reaches this machine at 10.0.2.2,
// so the Android build gets that address instead of localhost):
//   npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors
//   ( cd apps/host && MF_CDN_BASE=http://localhost:8000 npm start )

import { execSync } from 'node:child_process';
import { cpSync, mkdirSync, rmSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
const REMOTES = { listApp: 'list', partyApp: 'party' };
const ALL_PLATFORMS = ['ios', 'android'];

const [platformArg] = process.argv.slice(2);
if (platformArg && !ALL_PLATFORMS.includes(platformArg)) {
  console.error(`Unknown platform "${platformArg}". Use one of: ${ALL_PLATFORMS.join(', ')}`);
  process.exit(1);
}
const platforms = platformArg ? [platformArg] : ALL_PLATFORMS;

const cdnRoot = join(repoRoot, 'cdn-root');

for (const platform of platforms) {
  // Wipe this platform only, so building one does not delete the other's tree.
  rmSync(join(cdnRoot, platform), { recursive: true, force: true });
  mkdirSync(join(cdnRoot, platform), { recursive: true });

  for (const [remote, app] of Object.entries(REMOTES)) {
    console.log(`\n=== building ${remote} (${platform}) ===`);
    const appDir = join(repoRoot, 'apps', app);
    execSync(`npm run bundle:${platform}:prod`, { cwd: appDir, stdio: 'inherit' });
    cpSync(join(appDir, 'cdn', platform, remote), join(cdnRoot, platform, remote), {
      recursive: true,
    });
    console.log(`copied -> cdn-root/${platform}/${remote}`);
  }
}

const HOST_ADDRESS = { ios: 'http://localhost:8000', android: 'http://10.0.2.2:8000' };
console.log(`\nCDN assembled at ${cdnRoot}`);
console.log('Serve it:             npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors');
for (const platform of platforms) {
  console.log(`Point the host at it: ( cd apps/host && MF_CDN_BASE=${HOST_ADDRESS[platform]} npm start )   # ${platform}`);
}

Sign what you ship

The chunks now leave the machine, and post 1's integrity cost starts here. The private key signs every production chunk and must never reach the repository, and this repository is public, so the ignore rule goes in before the generator exists. In .gitignore:

# Signing keys. The private key signs every production chunk and must never be committed:
# this directory is ignored before `node tools/gen-signing-keys.mjs` is ever run.
code-signing/

Ignore code-signing/ before you generate a key, not after. A private key that reaches a public repository is compromised the moment it is pushed. In this post the repair is a new key and a rebuild of every chunk the old one signed; once apps verify signatures, from post 15, it also means replacing the public key those apps trust, and with an embedded key that is an app update. Check that git status shows nothing under code-signing/ before every commit from here on.

Create tools/gen-signing-keys.mjs:

// --- Generates the keypair that signs every production remote chunk.
//
//   RSA-2048   signs each chunk Re.Pack's CodeSigningPlugin emits (an RS256 JWT of the chunk's
//              hash, appended to the bundle). The private half signs at build time; the public
//              half is what a host verifies against before it executes downloaded code.
//
// The private key lives in code-signing/, inside the checkout but git-ignored before this script
// is ever run, and it is written readable by its owner only: .gitignore keeps it out of commits,
// the file mode keeps it from other users of the machine. A pair is generated only when neither
// half exists. An existing private key is kept, never rotated: a chunk signed with a new key
// would not verify against a public key already embedded in installed apps, and a signature
// stays valid only for the key that made it. A missing public half is derived from the private
// one; a public half on its own, or a pair that does not match, stops the script.
//
// Usage: node tools/gen-signing-keys.mjs

import { createPrivateKey, createPublicKey, generateKeyPairSync } from 'node:crypto';
import { chmodSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
import { dirname, join } from 'node:path';
import { fileURLToPath } from 'node:url';

const repoRoot = join(dirname(fileURLToPath(import.meta.url)), '..');
const keyDir = join(repoRoot, 'code-signing');
mkdirSync(keyDir, { recursive: true });

const privatePath = join(keyDir, 'private-key.pem');
const publicPath = join(keyDir, 'public-key.pem');
const OWNER_ONLY = 0o600;

// Keys are compared as DER bytes, never as PEM text: line endings and wrapping are not identity.
const der = key => key.export({ type: 'spki', format: 'der' });

if (existsSync(privatePath)) {
  // The mode is re-applied on every run, because a copy or an earlier tool may have left it wider.
  chmodSync(privatePath, OWNER_ONLY);
  const derived = createPublicKey(createPrivateKey(readFileSync(privatePath)));
  if (!existsSync(publicPath)) {
    writeFileSync(publicPath, derived.export({ type: 'spki', format: 'pem' }));
    console.log('chunk-signing private key present; public key derived from it');
  } else if (!der(createPublicKey(readFileSync(publicPath))).equals(der(derived))) {
    console.error(
      `${publicPath} does not match ${privatePath}. Neither key's contents were changed: decide which key the installed apps trust before touching either file.`,
    );
    process.exit(1);
  } else {
    console.log('chunk-signing keypair already present, kept');
  }
} else if (existsSync(publicPath)) {
  // A public key with no private key is the one state this script must not repair on its own:
  // generating a fresh pair here would silently change the signing identity behind a public key
  // that may already be embedded in installed apps.
  console.error(
    `${publicPath} exists but ${privatePath} does not. Nothing was changed: restore the private key that made it, or plan a deliberate rotation and remove the public key by hand first.`,
  );
  process.exit(1);
} else {
  const { publicKey, privateKey } = generateKeyPairSync('rsa', { modulusLength: 2048 });
  writeFileSync(privatePath, privateKey.export({ type: 'pkcs1', format: 'pem' }), { mode: OWNER_ONLY });
  writeFileSync(publicPath, publicKey.export({ type: 'spki', format: 'pem' }));
  console.log('generated an RSA-2048 chunk-signing keypair');
}

console.log(`\nprivate key: ${privatePath}  (signs the chunks; never commit it, never ship it)`);
console.log(`public key:  ${publicPath}  (what a host checks the signature against)\n`);
console.log(readFileSync(publicPath, 'utf8').trim());

node tools/gen-signing-keys.mjs

Two of the script's choices are about the key's life after this post. The private half is written readable by its owner only, since .gitignore keeps it out of commits and the file mode keeps it from other users of the machine. And an existing pair is kept rather than rotated, and a public key on its own is never replaced: a chunk signed with a new key would not verify against a public key already embedded in installed apps, and a signature stays valid only for the key that made it. Once apps verify, rotating a key is a coordinated trust migration, with the old and new keys both trusted for a while or separate releases routed to each, and the posts that add verification and versioning own that design. This script refuses to start one by accident.

The remotes' configs add the plugin in production mode only. In both rspack.config.mjs files, at the end of plugins:

// Each production chunk gets an RS256 signature of its own hash, appended to the file. The
// private key sits in code-signing/, git-ignored inside the checkout, and never ships.
// Development builds stay unsigned by choice: their chunks are served from this machine
// and rebuilt on every save, and this post signs only what leaves it.
...(isProd
  ? [
      new Repack.plugins.CodeSigningPlugin({
        privateKeyPath: path.resolve(__dirname, '../../code-signing/private-key.pem'),
      }),
    ]
  : []),

Rebuild and read the end of the container:

( cd apps/list && npm run bundle:ios:prod ) && tail -c 1300 apps/list/cdn/ios/listApp/listApp.container.js.bundle | xxd | head -4

00000000: 646c 652e 6d61 703f 706c 6174 666f 726d  dle.map?platform
00000010: 3d69 6f73 2f2a 2052 4353 5342 202a 2f65  =ios/* RCSSB */e
00000020: 794a 6862 4763 694f 694a 5355 7a49 314e  yJhbGciOiJSUzI1N
00000030: 6949 7349 6e52 3563 4349 3649 6b70 5856  iIsInR5cCI6IkpXV

/* RCSSB */ is the marker, and what follows it is a JSON Web Token: the chunk's SHA-256 hash, signed with the private key using RS256. The plugin reserves the last 1,280 bytes of the file for the marker and the token, and pads the rest with zeros. The container and every chunk carry one. index.bundle does not, because the plugin skips the main bundle as always local.

A signature nobody verifies is a stamp, not a lock. Nothing in this build reads the token. Verification is ScriptManager's job, against a public key the app embeds as RepackPublicKey, and it arrives with the resolver in post 15. Re.Pack 5.2.5, the version this series runs, configures the plugin with enabled, privateKeyPath and excludeChunks and nothing else; 5.3.0, released on 5 August 2026, adds a publicKeyPath that embeds the key for you. The series stays on 5.2.5 and embeds it in the post that reads it, so the key and its reader arrive together. The arc from here: 14 signs, 15 verifies, 17 guards.

Serve it like production

A CDN, for everything this post does, is a server that returns static files at stable URLs. Build both remotes into one tree and serve it:

node tools/build-cdn.mjs ios

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

-c-1 turns the cache header off, so a rebuilt chunk is never served stale while you iterate. The host is the only app in the workspace with a remotes map: post 5 made the detail screen a package, and neither remote has consumed the other since. So the switch between the two worlds is one function in one file. In apps/host/rspack.config.mjs, above defineRspackConfig:

// --- Where the remotes are served from. Set MF_CDN_BASE and every remote URL below points at the
// content delivery network instead of the dev servers; leave it unset and nothing changes. The
// value is read at BUILD time and baked into the bundle, so a build that forgot it ships the dev
// URLs:
//   MF_CDN_BASE=http://localhost:8000 npm start      (the local CDN, on a development build)
//   MF_CDN_BASE=https://cdn.example.com npm run …    (a real one, on a release build)
const CDN_BASE = process.env.MF_CDN_BASE;

const DEV_REMOTES = {
  listApp: 'http://localhost:8082',
  partyApp: 'http://localhost:8083',
};

Inside it, before the returned config:

// The whole switch between the two worlds, in one function: dev server or CDN, same manifest
// filename either way. Nothing else in the workspace changes, because the host is the only app
// here that holds a remotes map.
const remoteUrl = name =>
  CDN_BASE
    ? `${name}@${CDN_BASE}/${platform}/${name}/mf-manifest.json`
    : `${name}@${DEV_REMOTES[name]}/${platform}/mf-manifest.json`;

remotes: {
  listApp: remoteUrl('listApp'),
  partyApp: remoteUrl('partyApp'),
},

Stop the two remote dev servers. Start the host's with the variable set, and build:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 npm start )

( cd apps/host && npm run ios )

The app looks exactly as it did at the end of post 13, which is the point. The proof is in the server's terminal:

[2026-09-17T22:34:47.686Z]  "GET /ios/partyApp/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.107Z]  "GET /ios/listApp/mf-manifest.json" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.283Z]  "GET /ios/partyApp/partyApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.283Z]  "GET /ios/listApp/listApp.container.js.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.461Z]  "GET /ios/partyApp/__federation_expose_partySlice.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.461Z]  "GET /ios/partyApp/__federation_expose_styles.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.473Z]  "GET /ios/listApp/vendors-node_modules_pokedex_detail_src_index_ts-node_modules_graphql-request_build_entrypoin-878711.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.475Z]  "GET /ios/partyApp/vendors-node_modules_react-navigation_native-stack_lib_module_index_js.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"
[2026-09-17T22:34:48.550Z]  "GET /ios/listApp/__federation_expose_ListStack.chunk.bundle" "Host/1 CFNetwork/3860.500.112 Darwin/27.0.0"

Two manifests, two containers, and the chunks the host could not provide: the detail package, which the host never bundles, and the native stack, which the host does not share, so the first remote to load supplies it for both. Not one request for React, React Native, Redux or the design system: the host provides all of those, as post 3's singleton contract requires.

Now break it

Every break-it in the series so far has broken a running app. This one happens before the app exists. Build the Release scheme with the tree exactly as it is now:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 npm run ios -- --mode Release )

                Welcome to Metro v0.84.5
              Fast - Scalable - Integrated

UnableToResolveError: Unable to resolve module ./global.css from …/react-native-module-federation/apps/host/index.js:

None of these files exist:
  * global.css(.ios.js|.native.js|.js|.ios.jsx|.native.jsx|.jsx|.ios.json|.native.json|.json|.ios.ts|.native.ts|.ts|.ios.tsx|.native.tsx|.tsx)
  * global.css

Read the first line, not the last. Metro started. Xcode's "Bundle React Native code and images" phase runs React Native's react-native-xcode.sh, and that script's default CLI_PATH is scripts/bundle.js: Metro's bundle command, called directly. The React Native CLI never gets to choose the bundler: bundle.js calls cli.js config only to read react-native.config.js's project config, then invokes Metro's bundle function directly, so the commands entry that points bundle at Re.Pack is never consulted. Metro then meets import './global.css' on line 6 of index.js and stops at the first thing it cannot do. The error names a stylesheet; the fault is which bundler ran. The fix is three variables the script already reads. Append to apps/host/ios/.xcode.env:

# --- The release bundle is built by Re.Pack, not Metro. Xcode's "Bundle React Native code and
# images" phase calls React Native's bundle script directly: that script reads
# react-native.config.js for the project config, through `cli.js config`, but never the
# `commands` entry that hands `bundle` to Re.Pack, so left alone it runs Metro, which knows
# nothing about global.css and stops there. CLI_PATH points the phase at the React Native CLI,
# which does honour that entry; BUNDLE_COMMAND names the command Re.Pack registers there;
# EXTRA_PACKAGER_ARGS hands it the Rspack config. $SRCROOT is this ios/ directory, so the app
# root is its parent. ---
export CLI_PATH="$SRCROOT/../node_modules/react-native/cli.js"
export BUNDLE_COMMAND=bundle
export EXTRA_PACKAGER_ARGS="--config $SRCROOT/../rspack.config.mjs"

Run the Release build again. It boots from the CDN with no dev server of any kind running, and the URLs sit in the bundle inside the app for anyone to check:

grep -ao 'http://[^"]*mf-manifest\.json' ~/Library/Developer/Xcode/DerivedData/Host-*/Build/Products/Release-iphonesimulator/Host.app/main.jsbundle

http://localhost:8000/ios/listApp/mf-manifest.json
http://localhost:8000/ios/partyApp/mf-manifest.json

Forget the variable on a release build and nothing complains: the dev-server URLs bake in instead, and this grep is how you find out before a tester does.

Android needs no change to reach Re.Pack. The Gradle plugin's bundleCommand defaults to bundle and its cliFile to react-native/cli.js, the route through the config file that Xcode's script skips, and android (Rspack 2.0.5) compiled appears inside :app:createBundleReleaseJsAndAssets. Three things differ, though. The emulator reaches your machine at 10.0.2.2, not localhost, so the variable changes with the platform:

( cd apps/host && MF_CDN_BASE=http://10.0.2.2:8000 npm run android -- --mode release )

Gradle decides whether to run the bundle task at all by comparing the task's declared inputs with the previous run, and an environment variable is not one of them. Change only MF_CDN_BASE and the task reports UP-TO-DATE, and the previous bundle ships. Declare the variable as an input, at the end of apps/host/android/app/build.gradle:

// --- MF_CDN_BASE is read by rspack.config.mjs when the bundle task runs, and Gradle cannot see
// that: an environment variable is not one of the task's declared inputs, so a build where only
// the value changed leaves createBundleReleaseJsAndAssets UP-TO-DATE and ships the previous
// bundle, dev-server URLs and all. Declaring it as an input makes a changed value rebuild the
// bundle and an unchanged one keep the cache. ---
tasks.configureEach {
    if (name.startsWith("createBundle") && name.endsWith("JsAndAssets")) {
        inputs.property("MF_CDN_BASE", System.getenv("MF_CDN_BASE") ?: "")
    }
}

And a release APK refuses plain http. React Native's Gradle plugin sets usesCleartextTraffic to false for release builds, and the boot dies on [ Federation Runtime ]: Failed to get manifest. #RUNTIME-003, with Network request failed underneath. A production CDN is served over https and never meets this. The local one is not, so a network security config permits the loopback addresses and nothing else. Create apps/host/android/app/src/main/res/xml/network_security_config.xml:

<?xml version="1.0" encoding="utf-8"?>
<!-- The local stand-in for a CDN is served over plain http on the build machine, which a release
     build refuses to talk to. This permits it for the loopback addresses only: localhost, 127.0.0.1
     and 10.0.2.2, the address an emulator reaches the machine on. A production CDN is served over
     https, where this exception does nothing at all. -->
<network-security-config>
    <domain-config cleartextTrafficPermitted="true">
        <domain includeSubdomains="true">localhost</domain>
        <domain includeSubdomains="true">127.0.0.1</domain>
        <domain includeSubdomains="true">10.0.2.2</domain>
    </domain-config>
</network-security-config>

and name it on the <application> element in AndroidManifest.xml:

android:networkSecurityConfig="@xml/network_security_config"

iOS needed no equivalent: the template's Info.plist already carries NSAllowsLocalNetworking, and the Release build reached localhost:8000 with no change.

Run it

Three terminals, and two are missing. The remotes' dev servers, one per remote in every post since post 2, do not start. Keys, build, serve:

node tools/gen-signing-keys.mjs && node tools/build-cdn.mjs ios

npx http-server@14.1.1 cdn-root -p 8000 -c-1 --cors

( cd apps/host && MF_CDN_BASE=http://localhost:8000 npm start )

( cd apps/host && npm run ios )

The release builds use the same tree and carry the URL on the build command, since that is where it is read:

( cd apps/host && MF_CDN_BASE=http://localhost:8000 npm run ios -- --mode Release )

node tools/build-cdn.mjs android && ( cd apps/host && MF_CDN_BASE=http://10.0.2.2:8000 npm run android -- --mode release )

Nothing in this post touches the code the suites cover, and they say so:

( for d in apps/host apps/list apps/party; do ( cd "$d" && npx jest --silent ) || exit 1; done )

Add two Pokémon, open the Party tab, run a Quick Battle. Everything post 13 built still works, and every request that made it work is a line in the server's log.

What you built, and what's next

Two remotes built for production, each chunk carrying a signature, laid out as the directory a CDN serves; a host that moves between the dev servers and that directory on one environment variable, read at build time; and a release build on each platform that boots from it with no dev server running. The app looks the same as it did in post 13. The terminals do not.

The limits, each with its owner. The CDN holds one version of each remote, so a new build replaces the old one for every installed binary at once, whether or not that binary can run it; post 15 adds versioned directories, a version map and a resolver that chooses at each launch. Nothing verifies the signatures; that resolver does, against a public key embedded beside it. An app that cannot reach the CDN has nothing to fall back to; post 16 puts a copy of each remote in the binary. And the map that will decide which version an app loads is itself unsigned until post 17.

Next: versioned remotes on the CDN, a version map, a per-launch resolver, and an old binary that never downloads code it cannot run.

Sources

Re.Pack: bundle — the production bundle command and its --dev, --entry-file, --platform and --config flags
Re.Pack: CodeSigningPlugin — the plugin's purpose and options; the page now documents the publicKeyPath that 5.3.0 added
Re.Pack: ScriptManager — verifyScriptSignature and the embedded RepackPublicKey it falls back to, the next post's work
Re.Pack: ModuleFederationV2Plugin — the name@url remotes format and the resolver runtime plugin the plugin adds by default
Re.Pack source: CodeSigningPlugin.ts at 5.2.5 — the /* RCSSB */ marker, the SHA-256 hash signed as an RS256 token, the 1,280-byte reservation, and the main bundle skipped as always local
Re.Pack source: ResolverPlugin.ts at 5.2.5 — every asset URL rebased onto the manifest URL the host fetched
callstack/repack#1390 — the default minimiser doing nothing under Rspack from terser-webpack-plugin 5.6.0, with the build still green
Re.Pack source: getMinimizerConfig.ts at 5.2.5 — terser-webpack-plugin chosen for every Rspack version but 1.4.11
React Native source: bundle.js at 0.85.3 — the script Xcode's phase calls: project config through cli.js config, then Metro's bundle function directly
Module Federation: manifest — mf-manifest.json and mf-stats.json, the default file names
React Native source: react-native-xcode.sh at 0.85.3 — CLI_PATH defaulting to Metro's scripts/bundle.js, and the BUNDLE_COMMAND and EXTRA_PACKAGER_ARGS variables the fix sets
React Native source: ReactExtension.kt at 0.85.3 — cliFile defaulting to cli.js and bundleCommand to bundle, which is why Android reaches Re.Pack unchanged
React Native source: AgpConfiguratorUtils.kt at 0.85.3 — usesCleartextTraffic set to false for release builds
Gradle: incremental build — up-to-date checks compare fingerprints of declared inputs, and inputs.property declares one
Android: network security configuration — cleartext off by default since Android 9, and the domain-config that permits it per host
Android: emulator network address space — 10.0.2.2 as the alias for the development machine's loopback interface
http-server — the -p, -c and --cors options
react-native-module-federation — the companion repo, the build at the tag post-14-production-build

shell.navigateTo: native screens from a federated remote in React Native

Warren de Leon — Mon, 21 Sep 2026 00:05:30 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 12 ended with the host offering the remotes a loan: its native side, through a bridge that launches a native screen from the Party tab and waits for the result. This post builds the bridge. A button in a federated tab opens a fully native screen, SwiftUI on one platform and Jetpack Compose on the other, and the battle's winner returns as one promise's resolution.

The constraint underneath has been in the series since post 1: runtime delivery moves JavaScript and nothing else. Post 11 met it at the design system, and Re.Pack's limitations list states the host's half of the deal: "Host application must have native modules used in other containers". A remote that wants a native screen cannot bring one. The host lends its own.

The loan's shape: a remote sees exactly one function, shellNavigate(destination, params?) from the contract, returning a promise. The title's shell.navigateTo is this function, under the contract's exported name. Behind it sit the host's routing table and the blog's first TurboModule (React Native's typed native-module system), with its first Swift and Kotlin beyond the template. The round trip:

📊 Diagram: view it on warrendeleon.com

One practical difference before the first command. Until now the clone was a convenience: everything was typed, and a tree built by hand since post 2 served just as well. This post is the first where the companion repo is required input: the native screens arrive from its tag, and by the time a TurboModule registers, your native project has to match the tag's. Start from post 12's finished state, the start tag:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-12-a11y-testing

The finished state is the end tag, post-13-native-handoff; a fetch later in the build reaches into it, and everything else you type.

One function in the contract

The contract gains one file, the remote's entire view of the native world. Create packages/contracts/src/shellNavigation.ts:

import type { PartyMember } from './party';

// --- The shell's routing surface, and the whole of what a remote knows about native. A remote
// imports `shellNavigate` and nothing else: no TurboModule, no native types, no idea whether the
// destination it names is another micro-app or a fully native screen. The host owns the table that
// decides, so migrating a native flow to React Native later is one row edit here and no change in
// any remote. ---

export type RouteEntry =
  /** Hands off to native: the host calls openNative, a native screen presents, and the promise
   *  resolves with whatever that screen passed back. */
  { type: 'native'; nativeId: string };

// One entry, because one thing dispatches. The union above is written as a union of one so a
// micro-app variant can join it without the readers of `entry.type` changing shape; a registry row
// with nothing behind it is a dead constant, and this series has already paid for one of those.
export const ROUTE_REGISTRY: Record<string, RouteEntry> = {
  QuickBattle: { type: 'native', nativeId: 'quickBattle' },
};

// --- What crosses the boundary, in both directions. These types live in the contract because the
// HOST has to serialise them, not because another app dispatches anything: the battle's outcome is
// the party's own business and the party's own reducer handles it. ---

/** RN -> native. The party hands over its members; the native screen shows and battles them.
 *
 *  The colour scheme travels with them because it has to. Every federated surface reads the one
 *  styling runtime the host mounts, and a native screen is the one consumer that cannot subscribe
 *  to it: there is no bundle to share and no provider to sit under. So the theme stops being
 *  ambient at this boundary and becomes an argument, sent at the moment of the call. */
export interface QuickBattleParams extends Record<string, unknown> {
  members: PartyMember[];
  colourScheme: 'light' | 'dark';
}

/** Native -> RN. The uid, not the id: two copies of the same Pokémon are two contestants, and the
 *  party has stamped a uid on each member since 3.1.0 for exactly that reason. Absent when the
 *  screen closed without a battle. */
export interface QuickBattleResult {
  winnerUid?: string;
}

/** Native resolves with an object, or with nothing when the flow ended without a result. */
export type ShellNavigateResult = Record<string, unknown> | undefined;

export type ShellNavigateFn = (
  destination: string,
  params?: Record<string, unknown>,
) => Promise<ShellNavigateResult>;

// --- The slot the host fills and every remote reads. It is a globalThis key rather than a React
// context because this package is bundled into the host AND into each remote: a context created
// here would be a different object in every bundle, so a remote's useContext would never find the
// host's provider. The module identity that posts 3 and 6 made a singleton for is exactly what is
// missing at this seam, and globalThis is the one slot all three bundles genuinely share. ---
const GLOBAL_KEY = '__POKEDEX_SHELL_NAVIGATE__';

export function registerShellNavigateHandler(fn: ShellNavigateFn): void {
  (globalThis as Record<string, unknown>)[GLOBAL_KEY] = fn;
}

export function shellNavigate(
  destination: string,
  params?: Record<string, unknown>,
): Promise<ShellNavigateResult> {
  const fn = (globalThis as Record<string, unknown>)[GLOBAL_KEY] as ShellNavigateFn | undefined;
  if (typeof fn !== 'function') {
    // No handler: warn and resolve. A remote that awaits this gets undefined and renders something
    // honest, which is the same tolerance the party slice's read shape is built on.
    console.warn(`[shellNavigate] no handler registered (called with ${destination})`);
    return Promise.resolve(undefined);
  }
  return fn(destination, params);
}

The comments carry the three decisions: one registry entry, since only one thing dispatches; the theme as an argument, since a native screen cannot subscribe to the styling runtime; and a globalThis slot rather than a React context, which bundling into every app would make a different object in each. Post 8's prepare-stamped uid gets its first cross-boundary consumer here: the value that leaves the app and comes back.

React Navigation's native stack deserves naming first, and for native-backed React Native screens inside a navigator it is the right tool. What it does not model is a screen the host owns natively, outside React's tree, taking input from one remote and returning a value to it. That round trip is the bridge's reason to exist.

Export it, bump, and publish through the same Verdaccio flow post 5 established. In packages/contracts/src/index.ts:

export * from './party';
export * from './shellNavigation';

In packages/contracts/package.json, "version": "3.3.0": an additive minor on post 12's 3.2.2. Two tooling edits come with it: the new file calls console.warn, so the contracts tsconfig.json adds "DOM" to its lib array as ui and a11y-testing already do, and the build script gains a dist clean so stale declaration files cannot survive into a publish:

"build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc",

Publish, then take it in all three apps:

( cd packages/contracts && npm install && npm run build && npm publish )

for app in host list party; do ( cd apps/$app && npm install @pokedex/contracts@3.3.0 ); done

The spec and the codegen

A TurboModule starts as a TypeScript spec, read at build time by React Native's code generation, which writes the base classes the native implementations extend. Create apps/host/specs/NativeShellNavigationModule.ts:

import type { TurboModule } from 'react-native';
import { TurboModuleRegistry } from 'react-native';

// --- The TurboModule spec: the one place the host's JavaScript and its native code agree on a
// signature. Codegen reads this file at build time and writes the C++/ObjC++ and Kotlin base
// classes the native implementations extend, which is why the file lives outside src/ and why
// its name has to start with `Native`.
//
// One method, and it is asynchronous by shape: openNative hands a native flow its input and
// resolves with whatever that flow passed back. The promise is the whole design — the party's
// await does not return until the native screen has finished, and every exit path of that screen
// has to settle it exactly once.
//
// The boundary is JSON strings in both directions rather than codegen object types. Codegen can
// carry structured objects, and a bigger bridge should let it; a string keeps the serialisation
// visible in one place on each side, which is easier to follow while the bridge is one method
// wide. ---

export interface Spec extends TurboModule {
  openNative(nativeId: string, paramsJson: string): Promise<string>;
}

// getEnforcing throws when no native module answers to the name: a binary built without the
// native half, or a codegen mismatch. React Native's own examples import a spec like this at
// module scope, and with the module in the binary that is fine. The host's handler requires this
// file lazily instead, as a choice about where that throw is allowed to land. Imported at boot,
// a missing native half kills the shell during bundle evaluation, before any error boundary
// exists; required at the call, the same fault surfaces at the button press, in a running app
// that can log it and carry on. Runtime delivery is what makes the skew real: JavaScript can
// arrive on a binary that never built the native side.
export default TurboModuleRegistry.getEnforcing<Spec>('ShellNavigationModule');

The boundary is JSON strings in both directions; the spec's opening comment ends on the why. Tell codegen where the spec lives, in apps/host/package.json:

"codegenConfig": {
  "name": "HostSpecs",
  "type": "modules",
  "jsSrcsDir": "specs",
  "android": {
    "javaPackageName": "com.host.specs"
  }
}

Codegen runs during pod install, so run it now:

( cd apps/host/ios && bundle exec pod install )

The host's handler is the routing table's reader. Create apps/host/src/shell/shellNavigation.ts:

import { ROUTE_REGISTRY, type ShellNavigateFn, type ShellNavigateResult } from '@pokedex/contracts';

import type { Spec as ShellNavigationSpec } from '../../specs/NativeShellNavigationModule';

// --- The host's half of shell.navigateTo. A remote calls the contract's shellNavigate; this is
// what runs. It looks the destination up in the routing table and hands native destinations to the
// TurboModule, JSON in and JSON out. The remote never learns which branch it took. ---

// The spec module calls TurboModuleRegistry.getEnforcing at import, and that throws when no
// native module answers to the name. Requiring it here, inside the call, decides where that
// throw can land: at the tap, in a running shell that logs it and carries on, rather than during
// boot evaluation, where a missing native half would kill the app with no error boundary.
function nativeModule(): ShellNavigationSpec {
  return require('../../specs/NativeShellNavigationModule').default as ShellNavigationSpec;
}

export const shellNavigateHandler: ShellNavigateFn = async (destination, params) => {
  const entry = ROUTE_REGISTRY[destination];
  if (!entry) {
    // An unknown destination is a caller's bug, not a crash: warn and resolve, so a remote built
    // against a newer contract than the host degrades to nothing happening.
    console.warn(`[shellNavigate] unknown destination: ${destination}`);
    return undefined;
  }

  const resultJson = await nativeModule().openNative(entry.nativeId, JSON.stringify(params ?? {}));
  if (!resultJson) {
    return undefined;
  }
  try {
    return JSON.parse(resultJson) as ShellNavigateResult;
  } catch {
    // A native result that does not parse is a native-side bug, and not a reason to detonate the
    // remote's await: warn and resolve, the same tolerance every other edge of this seam shows.
    console.warn(`[shellNavigate] unparseable native result for ${destination}`);
    return undefined;
  }
};

The lazy require() chooses where a missing native half fails: at the tap, not at boot. getEnforcing throws when no module answers to the name. React Native's own examples import a spec at module scope, which works while the module is in the binary; runtime delivery makes the skew real. At boot the fault is a white screen with no error boundary; at the call, a loggable failure on one button.

Registration is two lines in apps/host/App.tsx:

import { partyStateReady, registerShellNavigateHandler } from '@pokedex/contracts';
// ...
import { store } from './src/store';
import { shellNavigateHandler } from './src/shell/shellNavigation';

// The host fills the contract's navigation slot once, at module scope, before any remote can
// render and call shellNavigate. Registering the handler touches no native code — the TurboModule
// is not reached until a destination is actually navigated to — so this is safe at import in a way
// that requiring the spec here would not be.

registerShellNavigateHandler(shellNavigateHandler);

Type the bridge, fetch the screens

From here the work splits by what each half teaches. The bridge is federation, and you type all of it: the module holding a promise open across the boundary, its registration, the threading rules. The screens are SwiftUI and Compose UI code, so they arrive from this post's own end tag. Around a thousand lines stay off your keyboard, none unexplained.

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-13-native-handoff /tmp/pokedex-ref-13
cp /tmp/pokedex-ref-13/apps/host/ios/Host/QuickBattle.swift apps/host/ios/Host/QuickBattle.swift
cp /tmp/pokedex-ref-13/apps/host/android/app/src/main/java/com/host/QuickBattleActivity.kt apps/host/android/app/src/main/java/com/host/QuickBattleActivity.kt
cp /tmp/pokedex-ref-13/apps/host/__tests__/shellNavigation.test.ts apps/host/__tests__/shellNavigation.test.ts
cp /tmp/pokedex-ref-13/apps/party/__tests__/quickBattle.test.tsx apps/party/__tests__/quickBattle.test.tsx
mkdir -p apps/host/android/app/src/test/java/com/host apps/host/ios/HostTests
cp /tmp/pokedex-ref-13/apps/host/android/app/src/test/java/com/host/ShellNavigationModuleTest.kt apps/host/android/app/src/test/java/com/host/ShellNavigationModuleTest.kt
cp /tmp/pokedex-ref-13/apps/host/ios/HostTests/QuickBattlePresenterTests.swift apps/host/ios/HostTests/QuickBattlePresenterTests.swift

Both screens wear the design system. No bundle crosses this boundary, so each file mirrors colours.ts and the eighteen type colours by hand, rebuilt into the card language the Pokédex grid renders: tinted sprite disc, hashed number pill, type badges, accent foot. Each resolves the colourScheme the params carry against the same pairs the dark: rules use; the Compose buttons declare Role.Button, since a styled Text otherwise announces to TalkBack as plain text; and each screen wears a purple NATIVE badge. No federated screen carries one, so a screenshot declares its side of the boundary on its own.

Four suites arrive with the screens. The JavaScript pair pins the bridge's seam: the host's, the contract slot and the handler, unparseable results included; the party's, the button's gating and the winner landing through the private action. The native pair holds the promise guarantees the next two sections build, wired in after the exit table.

iOS: every exit resolves

The iOS module is Objective-C++, and the extension is the point: getTurboModule returns the generated JSI module (JavaScript Interface, the C++ layer under the new architecture) as a std::shared_ptr, which Swift cannot express. The screen stays pure SwiftUI; the .mm is a thin adapter. In Xcode, create ShellNavigationModule.h and ShellNavigationModule.mm in the Host group, which puts them in the target, and add the fetched QuickBattle.swift with File → Add Files to "Host".

#import <Foundation/Foundation.h>
#import <React/RCTBridgeModule.h>
#import <HostSpecs/HostSpecs.h>

// --- The host's native half of shell.navigateTo on iOS. Codegen read specs/
// NativeShellNavigationModule.ts and wrote NativeShellNavigationModuleSpecBase and the
// NativeShellNavigationModuleSpec protocol into HostSpecs; this class subclasses the one and
// conforms to the other, which is what makes the JavaScript `openNative` land here.
//
// The header exists because the implementation is ObjC++ (.mm) rather than Swift: returning the
// generated C++ JSI module from getTurboModule needs C++, and Swift cannot. The screen it
// presents is pure SwiftUI — see QuickBattle.swift. ---
@interface ShellNavigationModule : NativeShellNavigationModuleSpecBase <NativeShellNavigationModuleSpec>
@end

#import "ShellNavigationModule.h"
#import <HostSpecs/HostSpecs.h>
// Host-Swift.h declares every @objc Swift class in this app, which is how this ObjC++ file reaches
// QuickBattlePresenter. Imported after the app-delegate header so the generated header's forward
// references resolve in this translation unit.
#import <React-RCTAppDelegate/RCTDefaultReactNativeFactoryDelegate.h>
#import "Host-Swift.h"

// --- The TurboModule implementation. Two things live here and nothing else: the registration
// that puts the module in the registry under the name the spec asked for, and openNative.
//
// openNative is where the promise starts. It hands the resolve block to the presenter and returns
// immediately; the block is called later, from the native screen, whenever that screen finishes.
// Until then the party's `await` is genuinely suspended. That is the whole handoff, and it is also
// the whole risk: a path through the native screen that never calls the block leaves the promise
// pending for the life of the process. ---
@implementation ShellNavigationModule

RCT_EXPORT_MODULE()

- (void)openNative:(NSString *)nativeId
        paramsJson:(NSString *)paramsJson
           resolve:(RCTPromiseResolveBlock)resolve
            reject:(RCTPromiseRejectBlock)reject
{
  [QuickBattlePresenter presentWithNativeId:nativeId
                                 paramsJson:paramsJson
                                 completion:^(NSString *_Nonnull resultJson) {
                                   resolve(resultJson);
                                 }];
}

// The codegen C++ module. This method is the reason the file is ObjC++ rather than Swift: it
// returns a std::shared_ptr, which Swift has no way to express.
- (std::shared_ptr<facebook::react::TurboModule>)getTurboModule:
    (const facebook::react::ObjCTurboModule::InitParams &)params
{
  return std::make_shared<facebook::react::NativeShellNavigationModuleSpecJSI>(params);
}

@end

What happens to that resolve block is the post's core. Every exit of the native screen settles the promise, exactly once, and every path lands in a settle-once wrapper. The call arrives off the main thread, so presentation hops before touching UIKit; the host controller comes from hostProvider, a static variable defaulting to a key-window scan, reassigned only by the unit bundle; a re-entrancy guard settles a refused second presentation; the sheet blocks interactive dismissal; and two safety nets close the exits no button took. One catches a sheet that left the screen outside finish(). The other catches a presentation UIKit silently refused, and its mechanism assumes nothing: whether the completion of a refused present() runs is not documented. One main-queue turn later a refused controller still has no presentingViewController, and none means nobody will ever dismiss the sheet, so the wrapper settles it:

// Every path below funnels into this, and it settles at most once. The battle's own exits
// race the two safety nets further down, and whichever lands first wins; the rest become
// no-ops instead of double settles.
var settled = false
let settle: (String) -> Void = { resultJson in
  guard !settled else { return }
  settled = true
  isPresenting = false
  completion(resultJson)
}

// openNative arrives on the TurboModule's own queue, not the main thread. Every UIKit call
// below has to be on main, so hop before touching anything.
DispatchQueue.main.async {
  guard let host = Self.hostProvider(), !isPresenting else {
    // Nothing to present from, or one flow already up: settle rather than wedge.
    completion("{}")
    return
  }
  isPresenting = true

  // The result settles BEFORE the dismissal starts, not in its completion. viewDidDisappear
  // fires while the sheet is still animating out, so a settle scheduled after the transition
  // would lose the race to safety net one and the winner would arrive as "{}".
  let view = QuickBattleView(contestants: contestants, isDark: isDark) { resultJson in
    settle(resultJson)
    host.dismiss(animated: true)
  }

  let controller = QuickBattleHostingController(rootView: view)
  controller.modalPresentationStyle = .pageSheet
  // Exit only through the screen's own controls. An interactive swipe-to-dismiss would tear
  // the sheet away without reaching the settle above, leaving the promise pending.
  controller.isModalInPresentation = true
  // Safety net one: the sheet leaving the screen by any route the buttons did not take —
  // an ancestor being torn down is enough. A resultless settle beats a pending promise.
  controller.onDisappear = { settle("{}") }
  // Safety net two: present() silently does nothing when the host is mid-transition for
  // reasons this file cannot see. Whether UIKit runs the completion of a refused present is
  // not documented, so nothing here depends on it: one main-queue turn later, a presented
  // controller has a presentingViewController and a refused one still has none, and nil
  // means nobody will ever dismiss this sheet, so settle now.
  host.present(controller, animated: true)
  DispatchQueue.main.async {
    if controller.presentingViewController == nil {
      settle("{}")
    }
  }
}

One order matters: the result settles before the dismissal starts, because viewDidDisappear fires mid-animation. In the view, both exits, Close and Done, land in one finish(), and a battle-free exit is a result rather than an error:

private func finish() {
  guard let winnerId else {
    onDone("{}")
    return
  }
  let json = (try? JSONSerialization.data(withJSONObject: ["winnerUid": winnerId]))
    .flatMap { String(data: $0, encoding: .utf8) } ?? "{}"
  onDone(json)
}

A never-settled promise has no safety net. No timeout on the bridge, no garbage-collector rescue, no error to observe: the await simply never returns, and the resolve block and everything it captures stay retained for the life of the process. The opposite fault costs a log line at worst, since the bridge ignores a second settle. Resolving on every exit is mandatory; resolving twice is survivable.

Android: every exit is a result

Android gets most of the guarantee from structure: the screen is an Activity started for a result, the platform reports back every exit of a screen that opened, and the module's listener is the single place a delivered result settles it. What structure does not cover is the launch itself (a start that throws, or a teardown racing the UI-thread hop), so the module closes both by hand. Create apps/host/android/app/src/main/java/com/host/ShellNavigationModule.kt:

package com.host

import android.app.Activity
import android.content.Intent
import com.facebook.react.bridge.BaseActivityEventListener
import com.facebook.react.bridge.Promise
import com.facebook.react.bridge.ReactApplicationContext
import com.host.specs.NativeShellNavigationModuleSpec

// --- The host's native half of shell.navigateTo on Android, and the mirror of the iOS
// ShellNavigationModule. Codegen read the same spec file and wrote NativeShellNavigationModuleSpec
// into com.host.specs; this class extends it, so the JavaScript `openNative` lands here.
//
// Android's shape does most of the promise discipline for it. The screen is an Activity started
// for result, so the platform delivers a result for every exit of a screen that opened — the Done
// button, the system back gesture — and onActivityResult is the single place a delivered result
// settles the promise. What structure does not cover is the launch itself: a start that throws,
// or a teardown racing the UI-thread hop. Those two windows are closed by hand below. ---
class ShellNavigationModule(reactContext: ReactApplicationContext) :
  NativeShellNavigationModuleSpec(reactContext) {

  // Held from the moment the Activity is launched until it returns. One at a time, which is the
  // counterpart of the iOS presenter's isPresenting flag. Both fields are touched from the
  // native-modules thread (openNative, invalidate) and the UI thread (the launch block, the
  // result listener), so every mutation sits inside synchronized(this).
  private var pendingPromise: Promise? = null

  // Flipped once in invalidate and never back: a launch queued before teardown must not open a
  // screen after it, because nobody is listening and its result could land on a later battle.
  private var invalidated = false

  private val activityEventListener =
    object : BaseActivityEventListener() {
      override fun onActivityResult(
        activity: Activity,
        requestCode: Int,
        resultCode: Int,
        data: Intent?,
      ) {
        if (requestCode != QUICK_BATTLE_REQUEST) return
        // Every exit lands here. A battle that finished carries its JSON; a back gesture carries
        // no data at all, and an empty object is the honest answer for it — the party reads a
        // missing winnerUid as "nothing happened".
        val result = data?.getStringExtra(QuickBattleActivity.EXTRA_RESULT_JSON) ?: "{}"
        synchronized(this@ShellNavigationModule) {
          pendingPromise?.resolve(result)
          pendingPromise = null
        }
      }
    }

  init {
    reactApplicationContext.addActivityEventListener(activityEventListener)
  }

  override fun openNative(nativeId: String, paramsJson: String, promise: Promise) {
    val activity = reactApplicationContext.currentActivity
    if (activity == null) {
      // Nothing to launch from: settle now rather than leave the caller waiting on a result
      // that will never be delivered.
      promise.resolve("{}")
      return
    }
    synchronized(this) {
      if (pendingPromise != null || invalidated) {
        // A battle already running, or the module already torn down: same answer.
        promise.resolve("{}")
        return
      }
      pendingPromise = promise
    }
    // nativeId goes unread: one native flow exists today, and a second registry row would need a
    // switch here first. openNative arrives on a background queue; hop to the UI thread to start
    // the Activity rather than assume the queue is safe to start it from.
    activity.runOnUiThread {
      synchronized(this) {
        // invalidate can run between the queueing above and this block: the promise is settled
        // by then, and launching anyway would open a screen nobody is listening to.
        if (invalidated || pendingPromise == null) return@runOnUiThread
        try {
          val intent =
            Intent(activity, QuickBattleActivity::class.java).apply {
              putExtra(QuickBattleActivity.EXTRA_PARAMS_JSON, paramsJson)
            }
          activity.startActivityForResult(intent, QUICK_BATTLE_REQUEST)
        } catch (e: Exception) {
          // A launch that throws leaves no Activity to deliver a result. Settle now, or the
          // await outlives a screen that never opened.
          pendingPromise?.resolve("{}")
          pendingPromise = null
        }
      }
    }
  }

  override fun invalidate() {
    // A dev reload or host teardown while a battle is open would strand the caller's await:
    // the listener is about to go away, so settle the pending promise the way a resultless
    // exit does before it can no longer be settled at all, and refuse any launch still queued.
    synchronized(this) {
      invalidated = true
      pendingPromise?.resolve("{}")
      pendingPromise = null
    }
    reactApplicationContext.removeActivityEventListener(activityEventListener)
    super.invalidate()
  }

  companion object {
    private const val QUICK_BATTLE_REQUEST = 0xB47
  }
}

iOS registered itself with one macro; Android writes the registration down, in a package class the template leaves a slot for. The com.host.specs base class appears at the first Gradle build, when Android's codegen runs, so an editor complaining before then is early rather than wrong. Create apps/host/android/app/src/main/java/com/host/HostNativePackage.kt:

package com.host

import com.facebook.react.BaseReactPackage
import com.facebook.react.bridge.NativeModule
import com.facebook.react.bridge.ReactApplicationContext
import com.facebook.react.module.model.ReactModuleInfo
import com.facebook.react.module.model.ReactModuleInfoProvider
import com.host.specs.NativeShellNavigationModuleSpec

// --- Registration. iOS gets this for free from RCT_EXPORT_MODULE and autolinking; Android wants
// it written down, in two halves. getModule builds the instance when the registry asks for it by
// name, and getReactModuleInfoProvider declares what that name is and how it behaves — the last
// flag is the one that matters here, because it is what marks the module as a TurboModule rather
// than a legacy bridge module.
//
// The package is added to MainApplication's list, in the slot the React Native template leaves
// commented for exactly this. ---
class HostNativePackage : BaseReactPackage() {

  override fun getModule(name: String, reactContext: ReactApplicationContext): NativeModule? =
    when (name) {
      NativeShellNavigationModuleSpec.NAME -> ShellNavigationModule(reactContext)
      else -> null
    }

  override fun getReactModuleInfoProvider() = ReactModuleInfoProvider {
    mapOf(
      NativeShellNavigationModuleSpec.NAME to
        ReactModuleInfo(
          NativeShellNavigationModuleSpec.NAME,
          ShellNavigationModule::class.java.name,
          false, // canOverrideExistingModule
          false, // needsEagerInit
          false, // isCxxModule
          true, // isTurboModule
        )
    )
  }
}

In MainApplication.kt, the template's commented slot finally gets used:

PackageList(this).packages.apply {
  // The host's own native modules. Autolinking finds packages in node_modules; a module
  // that lives in the app itself is added here, in the slot the template leaves for it.
  add(HostNativePackage())
},

The fetched screen is the repo's first Jetpack Compose, so the build declares the compiler and the libraries. In apps/host/android/build.gradle:

classpath("org.jetbrains.kotlin:kotlin-gradle-plugin")
// Kotlin 2.x ships the Compose compiler as a separate plugin; the native Quick Battle
// screen is the only thing in the app that needs it.
classpath("org.jetbrains.kotlin:compose-compiler-gradle-plugin:$kotlinVersion")

In apps/host/android/app/build.gradle, the plugin, the build feature, and the dependencies:

apply plugin: "org.jetbrains.kotlin.android"
apply plugin: "org.jetbrains.kotlin.plugin.compose"

// Jetpack Compose, for the native Quick Battle screen (the SwiftUI counterpart on iOS).
buildFeatures {
    compose true
}

// --- Jetpack Compose, for QuickBattleActivity. The BOM pins the Compose family from one
// version, so those artefacts carry none of their own; activity-compose sits outside the
// BOM and pins itself. ---
def composeBom = platform("androidx.compose:compose-bom:2024.09.03")
implementation(composeBom)
implementation("androidx.compose.ui:ui")
implementation("androidx.compose.foundation:foundation")
implementation("androidx.compose.material3:material3")
implementation("androidx.activity:activity-compose:1.9.3")

The Activity joins AndroidManifest.xml, unexported:

<!-- The native Quick Battle screen. exported=false: nothing outside this app launches it;
     the shell's TurboModule does, with startActivityForResult. -->
<activity
  android:name=".QuickBattleActivity"
  android:exported="false"
  android:theme="@style/AppTheme" />

Read the fetched Activity's exit against the Swift version: Done calls deliverResult; the system back button calls nothing, and needs nothing:

// RESULT_OK with the JSON extra is what ShellNavigationModule's ActivityEventListener reads.
// A system back never reaches this method, and does not need to: the Activity finishes with no
// result, and the listener reads a null Intent as an empty object.
private fun deliverResult(resultJson: String) {
  setResult(Activity.RESULT_OK, Intent().putExtra(EXTRA_RESULT_JSON, resultJson))
  finish()
}

On iOS every exit resolves because the code closed each one; on Android, because the platform reports back every exit of a screen that opened, and the module closes the launch paths by hand. The full set:

Exit	iOS	Android
Done after a battle	resolves `{"winnerUid": …}`	`RESULT_OK` extra, resolves `{"winnerUid": …}`
Close before battling	resolves `{}`	`RESULT_OK` extra, resolves `{}`
Swipe to dismiss	blocked by `isModalInPresentation`	not applicable, full-screen Activity
System back	no such gesture on a sheet	null Intent, resolves `{}`
Second `openNative` while one is open	the re-entrancy guard resolves it with `{}`	the pending-promise guard resolves it with `{}`
The launch itself fails	net two's nil check settles `{}`	the `catch` around the start resolves `{}`
Shell torn down mid-battle	the disappearance net settles `{}`	`invalidate()` settles `{}` and refuses a queued launch

The second-launch row is defence in depth: the party's in-flight flag, coming next, already blocks it from the UI.

Pin the guarantees

Half the table covers moments a simulator run cannot stage: a launch that throws, a teardown racing the hop, a presentation UIKit refuses. The two native suites fetched earlier hold them.

The Android suite is plain JVM: ShellNavigationModuleTest.kt drives the real module against mocked edges and walks the promise through eight paths. The mock Promise records its settlements; the mock Activity's runOnUiThread runs inline, or is captured and fired after invalidate(), which stages the teardown race. Two apps/host/android/app/build.gradle edits wire it up. In the android block:

// JVM unit tests for ShellNavigationModule run against the SDK's stub android.jar; default
// values instead of "not mocked" throws let a real Intent be constructed as a no-op while
// the mocks around it carry the assertions.
testOptions {
    unitTests.returnDefaultValues = true
}

And in dependencies:

// --- JVM unit tests for the bridge module: the promise-settling contract under launch
// failure, teardown, and the result listener. Mockito 5 mocks finals by default, which is
// what lets Activity and the React context stand in without wrappers. ---
testImplementation("junit:junit:4.13.2")
testImplementation("org.mockito:mockito-core:5.14.2")
testImplementation("org.mockito.kotlin:mockito-kotlin:5.4.0")

The iOS suite needs one piece of project surgery, because the app is not its host. In Xcode: File → New → Target → Unit Testing Bundle, named HostTests, with "Target to be Tested" set to None; then select the fetched QuickBattlePresenterTests.swift and QuickBattle.swift and tick HostTests under Target Membership. If the new bundle is not in the Host scheme's Test action (Product → Scheme → Edit Scheme → Test), add it. The bundle compiles the presenter directly instead of loading the app, so its three tests need no React Native boot, dev server, or window hierarchy: no host to present from, a refused second presentation, and a presentation UIKit turns down. That last is the nil-check net observed as a test rather than trusted as a comment. The tests stage each case by reassigning the hostProvider seam.

Wire the button

The party's half starts in its slice; both new pieces stay private, in no contract, since nothing outside the party dispatches them. apps/party/src/partySlice.ts in full:

import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
import { addToParty, MAX_PARTY, rootReducer, type PartyMember } from '@pokedex/contracts';

// --- The party's state, owned outright by the party app. The contract carries the action creator
// and the read shape; this file carries what they mean. Nothing outside this app imports it — the
// host loads it as a federated module at boot, for the side effect at the bottom. ---
export const partySlice = createSlice({
  name: 'party',
  initialState: { members: [] as PartyMember[], lastBattleWinnerUid: null as string | null },
  reducers: {
    // Private: nobody else dispatches remove, so it ships in no contract.
    remove(state, action: PayloadAction<string>) {
      state.members = state.members.filter(m => m.uid !== action.payload);
      // A removed member cannot go on being the last winner; the banner would name a Pokémon
      // that is no longer in the party.
      if (state.lastBattleWinnerUid === action.payload) {
        state.lastBattleWinnerUid = null;
      }
    },
    // Also private, and deliberately so. The winner comes back from a native screen the HOST
    // presented, but it lands in the party's own state and nothing outside this app dispatches
    // it — so it appears in no contract. The handoff's params and result types are at the seam
    // because the host has to serialise them, which is a different reason from crossing.
    setLastBattleWinner(state, action: PayloadAction<string>) {
      state.lastBattleWinnerUid = action.payload;
    },
  },
  extraReducers: builder => {
    // The crossing interaction. The list app dispatches the contract's addToParty, and this case
    // matches it on the type string: addCase reads actionCreator.type and keys the reducer by
    // `party/add`, so agreement on that string is what makes the match work, not the identity of
    // the creator object. Sharing @pokedex/contracts as a singleton is what stops the two sides
    // from retyping that string, the cap and the read shape separately.
    builder.addCase(addToParty, (state, { payload }) => {
      if (state.members.length >= MAX_PARTY) return; // the cap lives with the owner
      state.members.push(payload);
    });
  },
});

export const { remove, setLastBattleWinner } = partySlice.actions;

// Importing this module is what adds the reducer to the shared store. rootReducer is the same
// object the host's configureStore wired in — that is why injection from a separately-built app
// works at all.
rootReducer.inject(partySlice);

Two of the party's own tests assert the slice's exact shape, so they grow the same field. In __tests__/partyStateReady.test.ts and __tests__/partySelfRecovery.test.tsx, the toEqual({ members: [] }) assertion becomes:

expect((store.getState() as PartySliceShape).party).toEqual({
  members: [],
  lastBattleWinnerUid: null,
});

PartyScreen.tsx grows in four places. First the imports:

import { useColorScheme } from 'nativewind';
import {
  MAX_PARTY,
  partyStateReady,
  shellNavigate,
  type PartyMember,
  type PartySliceShape,
  type QuickBattleResult,
} from '@pokedex/contracts';
import { Box, Button, ButtonText, EmptySlot, PokemonCard, ScreenContainer, Text, toast } from '@pokedex/ui';
import { remove, setLastBattleWinner } from './partySlice';

At module level, the owner's local read shape and the battle's floor:

// The owner's own view of its slice. The contract carries `members`, because foreign modules read
// it; the last winner is read here and nowhere else, so it stays out of the contract and is added
// to the shape locally instead.
type PartyOwnShape = PartySliceShape & {
  party?: { lastBattleWinnerUid?: string | null };
};

// Two contestants is the floor for a battle. Stated as a constant because the button's disabled
// state and the hint under it are two readings of the same rule.
const MIN_CONTESTANTS = 2;

Inside the component, the selectors and the handler:

const { colorScheme } = useColorScheme();
const members = useSelector((s: PartyOwnShape) => s.party?.members ?? EMPTY_MEMBERS);
const lastBattleWinnerUid = useSelector(
  (s: PartyOwnShape) => s.party?.lastBattleWinnerUid ?? null,
);
const lastWinner = members.find(m => m.uid === lastBattleWinnerUid) ?? null;

// The one call a remote makes to reach native. `shellNavigate` is the whole of what this app
// knows about the other side: no TurboModule import, no native types, no idea that the screen
// it opens is SwiftUI on one platform and Compose on the other. The host resolves the
// destination and owns everything past it.
//
// The await is the point. It does not return until the native flow has finished, and what comes
// back lands in this app's own state through this app's own action — the round trip starts and
// ends inside the party, so nothing about the battle needs to cross the contract.
const [battleInFlight, setBattleInFlight] = React.useState(false);
const onQuickBattle = React.useCallback(async () => {
  if (battleInFlight) return;
  setBattleInFlight(true);
  try {
    // The theme is read at the moment of the call, from the same NativeWind observable every
    // dark: class in the federation subscribes to. It is sent rather than observed because the
    // native screen has no way to subscribe: a toggle while the battle is open will not reach it.
    const result = (await shellNavigate('QuickBattle', {
      members,
      colourScheme: colorScheme === 'dark' ? 'dark' : 'light',
    })) as QuickBattleResult | undefined;
    // No winner is a real outcome, not a failure: the screen can be closed without battling,
    // and the native side resolves with an empty object when it is.
    if (result?.winnerUid) {
      dispatch(setLastBattleWinner(result.winnerUid));
    }
  } finally {
    setBattleInFlight(false);
  }
}, [battleInFlight, colorScheme, dispatch, members]);

The render gains the button, its hint, and the banner, after the slot grid:

{/* The handoff's one control. Disabled below two members, because a battle needs two
    contestants; the hint under it says which rule it is rather than leaving a dead
    button to explain itself. */}
<Button
  onPress={onQuickBattle}
  disabled={members.length < MIN_CONTESTANTS || battleInFlight}
  size="lg"
  className={`mt-6 rounded-xl ${
    members.length < MIN_CONTESTANTS ? 'bg-lightGrey dark:bg-white/10' : 'bg-purple'
  }`}
  // The 44pt minimum is declared, not inherited from the size variant, the same way the
  // detail's Add button declares it: the accessibility suite can only check what the
  // control states about itself.
  style={{ alignSelf: 'stretch', minWidth: 44, minHeight: 44 }}
  accessibilityRole="button">
  <ButtonText
    className={members.length < MIN_CONTESTANTS ? 'text-midGrey' : 'text-white'}>
    {battleInFlight ? 'Battling…' : 'Quick Battle'}
  </ButtonText>
</Button>
{members.length < MIN_CONTESTANTS ? (
  <Text size="xs" className="mt-2 text-center text-darkGrey dark:text-lightGrey">
    Add at least 2 Pokémon to battle.
  </Text>
) : null}

{/* What came back from native, rendered by the app that owns the state. */}
{lastWinner ? (
  <Text
    size="sm"
    className="mt-3 text-center font-semi text-darkGrey dark:text-lightGrey"
    accessibilityLiveRegion="polite">
    Last battle winner: {lastWinner.name}
  </Text>
) : null}

One change is easy to miss, and it cost this build a debugging session. The filled slots sit in a module-level React.memo, and a theme change alters none of their props, so the memo skips the subtree and the card keeps the old scheme's style objects: an empty white rectangle. The slot's key carries the scheme, so a toggle becomes a remount of six small cards:

// The key carries the colour scheme, and it has to. A theme change alters none of
// this slot's props, so the memo above finds them identical and skips the subtree;
// the card then keeps the style objects the styling runtime resolved for the old
// scheme and paints as an empty white rectangle. Keying by scheme makes a toggle a
// remount of six small cards, while the memo goes on doing its job within a theme.
// The Pokédex grid does not memoise its cards, which is why it never showed this.
<PartySlot
  key={`${member.uid}:${colorScheme}`}
  member={member}
  onOpen={openDetail}
  onRemoveMember={removeMember}
/>

Run it

Native code changed on both platforms, so both need real builds, as post 4's screens and post 11's animation pods did. This time the compiled code is the series' own. Three dev servers, each in its own terminal:

( cd apps/host && npm start )

( cd apps/list && npm run start:remote )

( cd apps/party && npm run start:remote )

Restart the host's dev server with --reset-cache if it was already running. A server started before contracts 3.3.0 was installed keeps serving the old resolution, and boot dies with TypeError: undefined is not a function at App.tsx: a cached contracts build with no registerShellNavigateHandler.

Then the builds, and the suites with them:

( cd apps/host && npm run ios )

( cd apps/host && npm run android )

for d in apps/host apps/party; do ( cd $d && npx jest --silent ); done

And the native suites, swapping the simulator name for one you have installed:

( cd apps/host/android && ./gradlew :app:testDebugUnitTest )

( cd apps/host/ios && xcodebuild test -workspace Host.xcworkspace -scheme Host -only-testing:HostTests -destination 'platform=iOS Simulator,name=iPhone 17 Pro' )

Add two Pokémon, open the Party tab, press Quick Battle. The native sheet rises wearing the grid's own cards, badge aside; Battle rings the winner in its type colour; Done dismisses; the banner names the winner the promise carried back. Flip the theme first and the native screen follows, from the scheme the call sent:

🎞️ Animated demo: watch it on warrendeleon.com

The badge is the only giveaway. That is the design system holding across a boundary no bundle crosses:

Now break it

With the round trip working, the bridge's dangerous property deserves one deliberate viewing. The presenter funnels every exit into its settle-once wrapper, so the honest sabotage is the one line every path trusts. In the fetched QuickBattle.swift, find the wrapper and comment out its last call:

var settled = false
let settle: (String) -> Void = { resultJson in
  guard !settled else { return }
  settled = true
  isPresenting = false
  // completion(resultJson)   <- break-it: the resolve never happens
}

Rebuild, open Quick Battle, battle, tap Done. The sheet dismisses normally, and back on the Party tab the button reads "Battling…" for the life of the process: the await never returns, so the finally that clears battleInFlight never runs. A second tap does nothing, blocked by the in-flight guard. No red box, no log line, no rejected promise. Neither safety net helped: net one fired its settle("{}") straight into the flipped settled guard, and net two had nothing to catch, since the presentation succeeded. The nets guard the paths into the wrapper, and nothing guards the wrapper's own last line. That is worth a moment: defence in depth ends somewhere, and wherever it ends is the line a review has to read hardest.

Nothing crashed, which is the problem.

The series has a small taxonomy of quiet failures, and this is the quietest. Post 8's lost add at least dispatched into a store and showed in devtools; this one leaves no trace, because nothing happened. Android cannot reproduce the same fault: empty out deliverResult, and the system back gesture still lands in onActivityResult with a null Intent and resolves {}. That is the exit table's asymmetry, observed. Restore the line and rebuild.

What you built, and what's next

A federated remote asked for a native screen and got one, without learning anything about native. The contract exposes one promise-returning function over a one-entry routing table; the host implements it with a TurboModule carrying JSON both ways, presenting SwiftUI on one platform and a Compose Activity on the other, both in the design system's tokens and theme. The winner's uid returns on the promise and lands through a private action, crossing no contract action, as post 7's ownership rules predict.

The honest limits: the bridge is one-way, so a native screen cannot yet ask the shell to navigate anywhere, and deep links do not route through the table; both are deliberate cuts and the bridge's next additions. The theme travels in the params, so a mid-battle toggle reaches the next battle, not the current one.

Next, the build gets real: a production bundle, and the first federated release artefact.

Sources

Re.Pack: Module Federation — the limitations list, including "Host application must have native modules used in other containers"
React Native: Turbo Native Modules introduction — the spec-first workflow this post follows on both platforms
React Native New Architecture working group: Turbo Modules guide — the worked promise-returning module example
React Native New Architecture working group: appendix — the type mappings, Promise<T> included
React Native: legacy Android native modules — the deferred-promise pattern around onActivityResult that the Kotlin module carries into the new architecture
React Navigation: native stack — the right tool for native-backed React Native screens, and the alternative this bridge is not competing with
Jetpack Compose BOM — the bill of materials pinning the Compose libraries to one version set
react-native-module-federation — the companion repo, the build at the tag post-13-native-handoff

Accessibility testing across federated remotes in React Native

Warren de Leon — Mon, 14 Sep 2026 00:05:03 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 11 closed on a promise: accessibility across the seam, a shared testing package that checks touch targets, contrast and focus order in remotes the host only meets at runtime. Two of those three fit in a Jest suite. Focus order does not, and What these checks cannot see says who it belongs to instead.

The problem is post 11's problem one level up. Three teams ship three bundles on their own schedules, each with its own idea of what counts as accessible, and those ideas drift exactly the way the greys drifted before a design system existed. Writing the bar down in a wiki page does not stop the drift, because a convention has no version and no install step. A package has both.

So the bar becomes @pokedex/a11y-testing: a Jest preset, a NativeWind-aware render, a small set of WCAG (Web Content Accessibility Guidelines) assertion helpers, the A and AA criteria catalogue, and a reporter. It publishes to the same local Verdaccio registry as every other package at the seam, and both source packages and both remotes install it. It is also the first @pokedex package that never reaches a bundle. Every consumer takes it as a devDependency, so no shared map changes and no runtime moves.

The criteria being checked are not this project's invention. The European Accessibility Act (Directive (EU) 2019/882) has applied since 28 June 2025 to the products and services it names. The Act itself sets functional requirements and names no standard; EN 301 549, which applies WCAG 2.1's A and AA criteria to mobile apps, is the standard that European practice measures against, and its revision to WCAG 2.2 is expected.

Why not jest-axe

On the web this is a solved problem with a package attached. jest-axe wraps axe-core, expect(await axe(container)).toHaveNoViolations() covers a wide slice of the rules in one line, and for a React web app it is the right first move.

axe-core tests HTML. jest-axe needs a jsdom environment, and its own README says colour contrast checks do not work in jsdom, so they are switched off even there. @axe-core/react-native is not a package at all: the npm registry answers 404. Deque, who maintain axe-core, do sell React Native tooling, including device SDKs that a native test run can call. That is the device-audit layer What these checks cannot see names, not the Jest one this post builds.

React Native Testing Library (RNTL) supplies the queries and the matchers and stops short of an audit. Nothing in its API returns a list of violations. Searching for prior art on accessibility testing across Module Federation remotes turned up nothing, in React Native or on the web. Two community packages come up when you search for React Native accessibility assertions, and neither is the shape this needs. react-native-accessibility-engine last published in 2022. react-native-ama is alive, though you have to know it moved: the unscoped package stopped at 0.7.5 in 2023 and the work moved to a scope. Seven of the eight @react-native-ama/* packages shipped 1.2.1 in August 2025, and five of the eight shipped a 2.0 beta in July 2026. It is a component library with dev-time runtime checks rather than a Jest assertion layer, so it answers a different question from the one in this post.

The bar gets assembled instead: a render that resolves classes, a handful of assertions, and a report.

📊 Diagram: view it on warrendeleon.com

Four arrows, two jobs. Two go to the packages that own the shared pixels, where a check runs once for everybody. Two go to the teams, where each suite covers the screens only that team composes.

The package

Start from post 11's tag:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-11-design-system

Three things have to be true before anything here runs, and all three are easy to assume you
already have. The local Verdaccio registry needs to be up with @pokedex/contracts,
@pokedex/ui and @pokedex/detail published to it, which is post 11's work. npm needs to know
that the @pokedex scope lives there. And you need to be logged in to that registry, which is
post 5's step rather than post 11's,
because the publishes later in this post are authenticated though the reads are not.

Start the registry first, because npm adduser below needs something to log in to:

npx verdaccio@6.2.0                              # :4873, leave it running

Set the other two once, for your user, because npm reads its project config from the directory
holding package.json, not from the repository root, so the repo's own .npmrc is invisible to
a command run inside packages/ui:

npm config set @pokedex:registry http://localhost:4873/
npm adduser --registry http://localhost:4873/     # only if you have not already

If you did not build post 11, its A package for the pixels and The detail finishes dressing
sections publish the three packages this one installs. apps/host needs its dependencies; the two remotes get theirs with their packages further down:

( cd apps/host && npm install )

The source is more than a post can usefully retype. Fetch the reference copy once and publish it the way post 5 and post 6 published theirs. The tag is released the day this post goes live, so degit can reach it:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-12-a11y-testing /tmp/pokedex-a11y-ref
cp -R /tmp/pokedex-a11y-ref/packages/a11y-testing packages/
( cd packages/a11y-testing && npm install && npm run build && npm publish )

The anatomy follows the packages before it: publishConfig points at Verdaccio, as it has since post 5, and react-native-builder-bob builds an ES-module lib/, the arrangement @pokedex/ui introduced in post 11. One deliberate omission. The package ships no exports map. Consumers reach for the root, /jest-preset in every Jest config, and /reporter.js in every test:a11y script, and a map has to name all three. Omit one and Node answers ERR_PACKAGE_PATH_NOT_EXPORTED, which for the preset means no test run at all.

jest-preset.js extends @react-native/jest-preset rather than replacing it, which is what lets every suite that already existed keep passing untouched. The two additions that matter here are both about NativeWind. nativewind/babel joins the transform presets, so className reaches the styling runtime as style instead of sitting there as an inert prop that makes every colour assertion read undefined. And react-native-css-interop/dist/test/setupAfterEnv.js joins setupFilesAfterEnv, which is where the toHaveStyle matcher lives. Neither line is what makes the checks in this post work (the contrast matrix reads the preset's colour object directly, and the component checks read class strings), but a shared preset has to serve the suite that does assert on a resolved style, and both are asserted present so a future edit cannot quietly drop them.

Two of the three entry points this package imports are undocumented. nativewind/babel is fine: it is step 3 of NativeWind's own installation guide. The other two are not written down anywhere. react-native-css-interop/dist/test/setupAfterEnv.js, which the preset adds to setupFilesAfterEnv, and nativewind/test, which the render imports, are real and shipped and power NativeWind's own suite, and nativewind.dev has no testing section at all. So the versions this is proven against are recorded rather than assumed: nativewind 4.2.6 and react-native-css-interop 0.2.6, carried on caret ranges and re-checked whenever NativeWind moves.

RNTL is held below 14 for a related reason: version 14 rewrote render, fireEvent and act as async, and this render path has not been exercised against it. Never reach for @testing-library/jest-native either; it is deprecated, and RNTL has shipped its own matchers since 12.4.

createThemedRender binds a Tailwind preset once and hands back the render every suite in that package uses:

const renderWithTheme = createThemedRender(require('@pokedex/ui/tailwind.preset.js'));

const { getByRole } = await renderWithTheme(<SomeButton disabled />);

Taking the preset as an argument keeps the accessibility package free of a dependency on the design system. It is a tool, not a member of the federation. Binding it to @pokedex/ui's own preset is what lets a suite resolve a class the way the app will, which is what the touch-target checks read and what the contrast helpers are computed against.

The helpers are plain functions that call the global expect, not expect.extend matchers. A helper imported by name needs no setup file, behaves identically in every package, and appears in a stack trace as itself. None of them import React Native: a test element is anything with props. Each one is tied to a success criterion (SC), and to the bar that criterion sets.

What it checks	Criterion	Level	The bar
Text on a surface	SC 1.4.3 Contrast (Minimum)	AA	4.5:1 normal text, 3:1 large
A control's own boundary	SC 1.4.11 Non-text Contrast	AA	3:1
What a screen reader reads out	SC 4.1.2 Name, Role, Value	A	name, role and state
Meaning not carried by colour	SC 1.4.1 Use of Color	A	the information is in words too
A change announced without moving focus	SC 4.1.3 Status Messages	AA	a role or live region carries it
Touch target	SC 2.5.5 Target Size (Enhanced)	AAA	44 by 44 CSS pixels

The touch-target row is the one to read twice. 44pt is this project's bar, and it is Apple's number rather than WCAG's. The current Human Interface Guidelines give iOS and iPadOS a default control size of 44 by 44 points and a minimum of 28 by 28, so 44 is the size Apple asks you to design to, not the smallest it will accept. An older Apple page, still widely quoted, says only "at least 44 points x 44 points", which is where the "Apple's minimum" shorthand comes from. On the WCAG side, SC 2.5.5 sits at Level AAA, and WCAG 2.2's AA criterion, SC 2.5.8 Target Size (Minimum), asks for 24 by 24 CSS pixels with five exceptions. Forty-four clears that comfortably. It does not clear everything: Android's guidance asks for at least 48dp, so a project that ships to both platforms and stops at 44 has taken Apple's recommended size and accepted that Android would prefer more. That is a decision worth making on purpose. Calling any of it "what WCAG AA requires" is the mistake to avoid.

The contrast helper uses 0.04045 in the channel linearisation. The relative-luminance definition carried 0.03928 before May 2021 and the older constant is still copied around widely. The spec's own note says the change has no practical effect on the results, and the current constant costs nothing.

The touch-target helper has one behaviour that decides how much the whole layer is worth: it throws where it cannot see, rather than passing. That applies per axis. A control declaring a height and no width has not been measured on its width, and substituting the bar for the axis nobody stated would report it as accessible at exactly the moment the test could not see it. A hitSlop is measured too, not merely noted as present, because hitSlop: 0 extends nothing.

That rule is the difference between a suite and a decoration, and it is the one this package got wrong first: an early version borrowed the bar for an undeclared axis, so a button that stated only its height passed on a width nobody had measured. It has its own regression test now, in the package's own suite.

Test the source

Both source packages install the bar and point Jest at it. @tailwindcss/container-queries is not optional here: the test render fails with Cannot find module without it.

( cd packages/ui && npm install -D @pokedex/a11y-testing@1.0.18 @testing-library/react-native@13.3.3 @tailwindcss/container-queries@0.1.1 @types/jest@29.5.14 @types/react-test-renderer@19.1.0 )
( cd packages/detail && npm install -D @pokedex/a11y-testing@1.0.18 @testing-library/react-native@13.3.3 @tailwindcss/container-queries@0.1.1 @types/jest@29.5.14 @types/react-test-renderer@19.1.0 )

The suites, the two Jest configs and the per-suite not-applicable declarations come from the reference copy, and each package gains a test:a11y script:

for pkg in ui detail; do
  cp /tmp/pokedex-a11y-ref/packages/$pkg/jest.config.js \
     /tmp/pokedex-a11y-ref/packages/$pkg/a11y-report.config.js \
     /tmp/pokedex-a11y-ref/packages/$pkg/.gitignore packages/$pkg/
done
mkdir -p packages/ui/src/tokens/__tests__ packages/ui/src/components/__tests__
cp /tmp/pokedex-a11y-ref/packages/ui/src/tokens/__tests__/contrast.accessibility.ts packages/ui/src/tokens/__tests__/
cp /tmp/pokedex-a11y-ref/packages/ui/src/components/__tests__/components.accessibility.tsx packages/ui/src/components/__tests__/
cp /tmp/pokedex-a11y-ref/packages/detail/__tests__/detail-view.accessibility.tsx packages/detail/__tests__/
cp /tmp/pokedex-a11y-ref/packages/detail/__tests__/detail-view.test.tsx packages/detail/__tests__/
cp /tmp/pokedex-a11y-ref/packages/ui/tsconfig.json packages/ui/
cp /tmp/pokedex-a11y-ref/packages/detail/tsconfig.json \
   /tmp/pokedex-a11y-ref/packages/detail/tsconfig.build.json packages/detail/

The design-system changes come across the same way. These are the token repairs the rest of this
section is about, and they have to be in the tree before the matrix can pass:

cp /tmp/pokedex-a11y-ref/packages/ui/tailwind.preset.js packages/ui/
cp /tmp/pokedex-a11y-ref/packages/ui/src/tokens/colours.ts \
   /tmp/pokedex-a11y-ref/packages/ui/src/tokens/typeColours.ts packages/ui/src/tokens/
cp /tmp/pokedex-a11y-ref/packages/ui/src/components/type-badge.tsx \
   /tmp/pokedex-a11y-ref/packages/ui/src/components/back-pill.tsx \
   /tmp/pokedex-a11y-ref/packages/ui/src/components/pokemon-card.tsx \
   /tmp/pokedex-a11y-ref/packages/ui/src/components/empty-slot.tsx packages/ui/src/components/

type-badge.tsx takes the two-surface decision the matrix is about to prove. The other three are
the same fault on smaller controls: the back pill's dark scrim, which the next section measures
alongside the badge's; the card's remove badge, whose touch target Same bar for every remote
comes back to; and the two secondary-text lines the card and the empty slot paint, which the
section after that repairs.

for pkg in packages/ui packages/detail; do
  ( cd $pkg && npm pkg set 'scripts.test:a11y=jest --testPathPattern accessibility --reporters=default --reporters=@pokedex/a11y-testing/reporter.js' )
done

packages/detail needs one more script change, and skipping it publishes a package that cannot be imported. Its suite lives in __tests__, so its tsconfig.json now includes that directory, which gives tsc two roots and moves the output down to dist/src/. package.json still declares dist/index.js. So set packages/detail's build script by hand, in its package.json, to the config that keeps src as the only root, clearing dist first so nothing from the old layout survives:

"build": "node -e \"require('fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.build.json"

A tsc that exits 0 and writes the files one directory too deep is the same fault as a green check measuring the wrong thing: nothing complains until whichever app installs the package first stops with Cannot find module.

packages/ui already had unit tests for its components. It gains an accessibility layer beside them, and the token matrix is the interesting half. Every foreground and background pair the design system promises is checked once, in the package that owns the tokens:

describe('WCAG 1.4.3 Contrast (Minimum) — type colours on the solid fill', () => {
  test.each(TYPE_NAMES)('%s badge text clears AA on its type fill', (type: string) => {
    expectColorContrast(
      hexForClass(textOnTypeClass(type)),
      hexForClass(bgClassForType(type)),
      'normalText',
    );
  });
});

hexForClass is the interesting part, and it is there because the first version of this file did not have it. That version mapped the class to a literal: 'text-black': '#000000'. All eighteen types passed, and the number it printed was true of a colour the app never painted.

The design system defines its own black. tailwind.preset.js sets black: '#2E3138' for near-black surfaces, which shadows Tailwind's default. So text-black painted #2E3138, and on the water fill that is 3.74:1 where the test itself demanded 4.5:1. Two of the eighteen were failing on screen while the matrix reported all eighteen green, because the matrix was measuring a constant instead of the token.

The repair is in two parts, and only the second one is durable. The badge foreground moved to its own token, typeInk, which is the real black the contrast map was computed against all along. And the matrix stopped writing hex at all: it resolves both sides of every pair out of the preset, so a token that is renamed or shadowed fails the suite rather than slipping past it. Both sides matter. An interim version resolved only the foreground and kept reading backgrounds from the token module, which left the same hole open on the other half: darkening a type fill to 1.64:1 still left all eighteen pairs green. Point typeInk back at #2E3138 in the preset now and six checks go red immediately: the water and psychic badges on their own fills, the rock, ghost and dragon badges on the hero surface, and the check that pins the preset to the token modules.

All eighteen fills pass now, and the sentence means something it did not mean before. A pair that passes here passes in every remote that composes it, and nobody re-checks a type badge in the Party app.

"Every remote that composes it" is carrying weight in that sentence, and it is worth being precise about what composing a pair means. A badge on a card sits on the type colour. A badge on the detail hero does not: the hero is the type colour, so a solid pill would vanish into it, and the hero variant lays a 30% white scrim down instead. That scrim is translucent but it is not transparent, and the foreground chosen for the solid fill is the wrong one for four of the six types dark enough to take white text on it. Rock, ghost, dragon and steel were landing at 3.17:1, 3.14:1, 3.39:1 and 2.71:1 on the surface they were actually drawn on, while the matrix checked a surface they were not.

So there are two decisions, not one, and the design system now computes both. The matrix composites the scrim exactly as the runtime composites it and checks the badge against that:

const scrim = composite(hexForClass('bg-white'), HERO_SCRIM_ALPHA, hexForClass(bgClassForType(type)));
expectColorContrast(hexForClass(textOnHeroScrimClass(type)), scrim, 'normalText');

Both faults have the same shape: a check measuring something adjacent to what ships. No green suite reveals it.

The floating back pill is the third of that shape, one control further out. It lays its own
translucent scrim over whichever hero it lands on, and it was painting bg-black/35, the
near-black neutral again, at 35%. On the three palest fills the white chevron came out at 2.81:1
on flying, 2.83 on ice and 2.84 on electric, under the 3:1 SC 1.4.11 asks of a control's own
boundary. Real black at the same alpha clears every fill, worst case 3.48.

It does not borrow typeInk for that. typeInk is a foreground: every use of it is a text-
class, and the experiment above reverts it to prove badge text moves. A scrim painted from the
same token would be dragged along by that experiment, which is how a decision about badge ink
would come to own an unrelated control. The background half of the same fact gets its own name:

export const BACK_PILL_SCRIM_ALPHA = 0.35;
export const BACK_PILL_SCRIM_CLASS = 'bg-scrim/35';

The matrix reads the token and the alpha out of that one class, so the value the pill paints and
the value the map composites cannot drift apart.

One token did not pass. midGrey (#9A9AB0) painted secondary text in four places on three light surfaces: two section headings on the detail sheet (2.60:1), the card's number line inside its grey pill (2.46:1), and the disabled Add button's label on its fill (2.02:1). The matrix recorded each surface separately, through a helper the package exports:

knownFinding('disabled button label on its fill', '2.02:1, exempt under 1.4.3 Incidental', () => {
  expectColorContrast(colours.midGrey, colours.lightGrey);
});

knownFinding wraps it.failing, which Jest reports as passing, so the suite stays green while the finding stays visible and the reporter lists it apart from the violations. The helper is there because the first version wrote that call by hand, with a title starting (known that the reporter matched on. A marker that is only a string is a marker one typo away from silence: misspell it and the reporter stops seeing a tracked finding, it.failing goes on reporting green, and a live violation reads as an ordinary pass. Writing the title in one place is what makes the marker impossible to misspell.

Two more surfaces joined the list once the matrix started resolving what it measures. The empty slot's caption is text-midGrey/70, not the token: composited over the app background it is 1.88:1. And everything so far was the light theme. Both remotes mount a theme toggle in their header, so every one of those surfaces has a dark counterpart the design system also composes, and text-midGrey carried no dark: override at either site. The card's number line sits on bg-white/10 over near-black at 3.44:1, and the empty slot's caption on navy at 3.82:1. Both are xs text, so both need 4.5:1.

Five pairs, then, every one of them below the bar and on a screen both apps ship. They stayed parked for five rounds behind a reason that reads well and does not survive arithmetic: there is no single darker value that fixes them. Past roughly #5F5F6D the token clears AA on the three light surfaces, and the detail sheet is dark:bg-navy, so a pair sitting at a comfortable 6.48:1 would drop to 2.84:1. All true, and none of it load-bearing, because nothing here needs a single value. The design system is theme-aware. It already shipped dark:text-lightGrey in eight other places, and secondary text had simply never been given the same treatment:

<Text size="xs" className="text-darkGrey dark:text-lightGrey">

packages/ui carries two of those four sites, and they arrive with the components copied earlier: the card's number line and the empty slot's caption, which now paints the token at full strength rather than at 70%. The other two are the detail sheet's section headings, so they are a hand edit in packages/detail/src/PokemonDetailView.tsx, on both of them:

// Both section headings. Secondary text is themed here like every other secondary
// line in the design system; the parked version had no dark override at all.
<Text size="xs" bold className="uppercase tracking-widest text-darkGrey dark:text-lightGrey">

The worst of the six pairs is now 6.94:1. Parking a finding is a real option and this post still keeps one, but "it is a palette decision" turned out to be cover for a change that took one class.

Then the matrix went green, and green was not enough. Putting text-midGrey back on the card afterwards left all one hundred and forty-nine checks passing, because a matrix measures pairs and never sees which class a component paints. That is the same hole the host's tab tints fall through, and it takes the same answer: a check that reads the component's own source.

expect(secondaryClass('pokemon-card.tsx')).toEqual({ light: 'darkGrey', dark: 'lightGrey' });

A render assertion would not have closed it. nativewind/test compiles only the tree handed to render, so a class a component picks inside its own render never compiles, and the assertion passes on nothing at all.

One finding stays tracked, and it is not a criterion failure. SC 1.4.3's Incidental exception exempts "text or images of text that are part of an inactive user interface component", so the disabled Add label has no contrast requirement to fail. It is tracked because this project would rather a disabled control stayed readable, and it sits under a Project bars heading that says so, rather than under 1.4.3 where it would be the same mis-citation the touch-target framing is careful to avoid.

packages/detail gets its own suite next, and the shape matters more there than the assertions: a component library that ships its own accessibility tests. The tests hand PokemonDetailView its props directly, which is the props seam from post 8 again. No store, no query client, no navigator. Both consumers inherit whatever this file proves, and when it finds something, one patch release repairs both of them. One ordering note if you run this suite early: it reads the hero-scrim decision out of @pokedex/ui, and post 11's lockfile pins a version that predates it. The suite runs, and twenty-four of its thirty checks fail, from four causes. Four throw textOnHeroScrimClass is not a function, which the design-system release further down repairs. One is the Add button's touch target, and one is the sheet's section headings still on the parked token. The other eighteen are one check per type, all saying the same thing about the hero's dex number, which the next section repairs in a single line. Three of those four causes are findings this post is about, so a red run here is the expected shape rather than a broken clone.

A failing test, then the fix

The failure this suite was built to catch did not happen. The expectation was the disabled Add button reporting no accessibilityState, so a screen reader would meet a button that greys out on screen and says nothing about being unavailable. It reports the state correctly. React Native's Pressable copies the disabled prop into accessibilityState itself:

_accessibilityState =
  disabled != null ? {..._accessibilityState, disabled} : _accessibilityState;

The test stays anyway, as a regression net rather than a fix. The day someone disables that button by swapping the handler for a no-op and greying the fill by hand, the state goes quiet and this test says so.

What did fail was the check beside it:

● WCAG 2.5.5 Target Size — the Add action › the Add button declares at least 44pt on both axes

  Element has no measurable size and no hitSlop; cannot verify the 44pt touch target.
  Give the control an explicit width/height or a hitSlop, or assert on a parent that
  has one.

Two things sit behind that line, and both reach past this button.

The button declared no size the suite could read. Its height came from gluestack's size="lg" variant, which composes px-6 h-11 while the component renders. In the app that class is fine: Tailwind scans the design system's source, finds the literal h-11, and the built bundle carries the rule. In the test tree it is not, and the reason is broader than this button. nativewind/test compiles the class strings it finds on the element tree you hand to render, and feeds those to Tailwind as its content. A class that appears inside a child component is not on that tree, so it never compiles: not one a variant builds, and not a literal one either. The Add button arrived carrying {"alignSelf": "stretch"} and nothing else, and the helper throws on nothing, which is the only reason this surfaced.

And h-11 is not 44 anyway. Tailwind generates .h-11 { height: 2.75rem }, and NativeWind's rem on React Native is 14, not the browser's 16. A literal <View className="h-11" /> renders height: 38.5, in the test tree and in the app alike. So the size that variant asks for was under Apple's 44 all along, whether or not any suite could see it. Two separate faults, one control: a size the test could not read, and a size that would not have cleared the bar if it had. Touch-target checks read declared style and props for this reason, rather than deriving a number from a class.

The fix puts the bar where a variant cannot quietly move it. In packages/detail/src/PokemonDetailView.tsx, on the Add button:

// The 44pt bar is declared here rather than inherited from the size variant.
// A variant is a visual decision that can change; the minimum tappable size of
// the screen's one primary action is a commitment, and the accessibility suite
// can only verify what the control actually declares. `alignSelf: 'stretch'`
// makes the button far wider than 44, but stretch is a layout instruction, not
// a measurement, so the minimum is stated on both axes.
style={{ alignSelf: 'stretch', minWidth: 44, minHeight: 44 }}

The same file carried the opposite fault, a hundred lines up, in the hero the button sits under. The
hero paints the type's colour full strength, and a comment above it explains that its text cannot be a
fixed colour, because the design system already decided per type and the hero should ask the token
rather than assume. The dex number under the name did assume. It muted itself:

// Before: a second answer, invented one line under the comment saying not to.
const heroMuted = heroInk ? 'text-white/70' : 'text-black/60';

text-black resolves to #2E3138 here, the neutral the preset warns is not a foreground, and at
60% over the fill it measures 2.21:1 on water. Sixteen of the eighteen types fail. No alpha rescues
it: sweep the value from 1% to 100% and the best case is full strength, where water still sits at
3.74:1, because the ink is the wrong ink. So the line asks what the name asks, in
packages/detail/src/PokemonDetailView.tsx:

// Delete heroMuted. The dex number takes the same decision the name takes.
<Text size="sm" className={`font-head ${onHero}`}>
  {dexNumber}
</Text>

Worst case becomes steel at 4.71:1, and the pair is one the token matrix already measures, so
nothing new needs adding to it. A muted variant would have needed its own row.

The Add button's fault sits one level lower too. The design system's ErrorState builds its retry from size="md", which is h-10, or 35 points, and that retry is the way back from a failed load in all three apps. Its declaration goes into the design system rather than into whichever app noticed first, in packages/ui/src/components/error-state.tsx:

// The retry is the way back from a failed load, so its tappable size is declared here
// rather than left to the size variant. A variant is a visual decision; the minimum
// target is a commitment, and a declared one is the only kind a suite can verify.
// Both axes are declared: the button is far wider than 44 in every layout it appears in,
// but a width nobody states is a width nobody has measured.
<Button
  action="primary"
  size="md"
  onPress={onRetry}
  style={{ minWidth: 44, minHeight: 44 }}>

One more finding sits beside them, in two components at once, and it is the one a sighted review never catches at all. Neither ErrorState nor LoadingState had any status semantics: no role, no live region, nothing. They looked correct, and to a screen reader a failed load simply happened in silence.

They do not get the same repair, because they are not the same kind of message. A failed load should interrupt; a spinner should not. So error-state.tsx becomes an alert, which announces on both platforms without a live region:

<Center className="flex-1 px-6" accessible accessibilityRole="alert">

and loading-state.tsx gets the polite variant, which waits for whatever the screen reader is already saying to finish:

<Center className="flex-1" accessible accessibilityLiveRegion="polite">

The design system carries five of these repairs and packages/detail three, so each is one release
rather than several:

( cd packages/ui && npm version 1.0.13 --no-git-tag-version && npm run build && npm publish )

( cd packages/detail && npm install @pokedex/ui@1.0.13 && npm version 4.0.12 --no-git-tag-version && npm run build && npm publish )

The host takes the release too, and it has a repair of its own, the only fault in this post
that lives in the shell rather than in a package or a remote:

cp /tmp/pokedex-a11y-ref/apps/host/App.tsx apps/host/
cp /tmp/pokedex-a11y-ref/apps/host/__tests__/TabBar.test.tsx apps/host/__tests__/
cp /tmp/pokedex-a11y-ref/apps/host/tsconfig.json apps/host/

Both tab labels are 10pt, and both were failing. The focused one took colours.blue, the brand
fill: 3.48:1 on the light bar, 3.74:1 on the dark. The unfocused one was never set at all, so
React Navigation derived it by mixing the theme's text halfway into the bar's own colour, which
gives 3.27:1 on white. One tab is always unfocused, so that pair is on screen whenever the
app is. colours.ts brings two readable blues with it; the greys are the ones every other
secondary line already uses:

tabBarActiveTintColor: mode === 'dark' ? colours.blueTextDark : colours.blueText,
tabBarInactiveTintColor: mode === 'dark' ? colours.lightGrey : colours.darkGrey,

TabBar.test.tsx is why the guard is worth its own file. The matrix in @pokedex/ui proves those
four pairs clear AA, and it cannot prove the host uses them: reverting the active tint to
colours.blue leaves every one of the design system's checks green. A matrix measures pairs; only
the app can be asked whether it composes them. It reads source rather than a render, because a
navigator option is resolved inside React Navigation and reaches no element a suite can query.

( cd apps/host && npm install @pokedex/ui@1.0.13 )

Two patch releases, three apps, and no coordination between the teams that ship them. The caret range every consumer already carried is what makes this a patch rather than a negotiation. The Pokédex suite records what that means in the place it is easiest to misread:

// This passes because the design system declares the size on ErrorState's button, not
// because this app did anything. One package release, every remote's retry covered.
expectMinTouchTarget(buttonContaining(getByText('Try again')));

It renders the same ErrorState in its remote-load boundary, so it moves to the same version as the two remotes rather than lagging behind them, which for a package the host provides as an eager singleton is not optional.

How far that retry gets you depends on what failed. A failed data request retries cleanly. A remote that never answered is a harder case: the boundary discards React's cached rejection and starts a fresh import, which is why the button visibly does something, but the same failure comes back every time. The runtime behaves as though it is still holding the failed manifest fetch underneath it. That is an observation rather than a documented guarantee, so treat the behaviour as the finding and not the cause. Clearing it needs cache-busting the runtime, and cache-busting is only worth having once there is something to fall back to, so both arrive together in the resilience post later in this series. What the checks in this post can say is narrower and still worth saying: whatever the retry does, it is reachable, it is named, and it is big enough to hit.

Same bar for every remote

Both remotes install the same three devDependencies, and take the two fixed packages in the same command:

( cd apps/list && npm install @pokedex/detail@4.0.12 @pokedex/ui@1.0.13 && npm install -D @pokedex/a11y-testing@1.0.18 @testing-library/react-native@13.3.3 @tailwindcss/container-queries@0.1.1 )

( cd apps/party && npm install @pokedex/detail@4.0.12 @pokedex/ui@1.0.13 && npm install -D @pokedex/a11y-testing@1.0.18 @testing-library/react-native@13.3.3 @tailwindcss/container-queries@0.1.1 )

Each app takes its own suite, its Jest config and its not-applicable declarations, and the README catches up with the tag:

for app in list party; do
  cp /tmp/pokedex-a11y-ref/apps/$app/jest.config.js \
     /tmp/pokedex-a11y-ref/apps/$app/a11y-report.config.js \
     /tmp/pokedex-a11y-ref/apps/$app/tsconfig.json apps/$app/
  cat /tmp/pokedex-a11y-ref/apps/$app/.gitignore > apps/$app/.gitignore
done
cp /tmp/pokedex-a11y-ref/apps/list/__tests__/ListStack.accessibility.tsx apps/list/__tests__/
cp /tmp/pokedex-a11y-ref/apps/party/__tests__/PartyStack.accessibility.tsx apps/party/__tests__/
cp /tmp/pokedex-a11y-ref/apps/list/src/PokedexScreen.tsx apps/list/src/
cp /tmp/pokedex-a11y-ref/apps/party/src/PartyScreen.tsx apps/party/src/
mkdir -p apps/party/__mocks__
cp /tmp/pokedex-a11y-ref/apps/party/__mocks__/styleMock.js apps/party/__mocks__/
cp /tmp/pokedex-a11y-ref/README.md .

The two screens carry the counter repairs. PokedexScreen.tsx has the live-region fix below, and
both screens paint the same count pill, whose numeral was text-darkGreen on bg-lightGreen:
1.53:1, 10.5pt bold, in each remote's header. darkGreen is #A6D3A0, the same value as
the grass fill, so the name was the only dark thing about it. Both now use text-darkGrey, the
colour the label beside them already used. At 7.18:1, it is a pair the token matrix has held
all along. The counter was composing a different one nobody had measured.

The styleMock.js is duller and just as necessary, and it is there because PartyStack pulls in global.css, one hop away through ./styles, so the remote's
classes reach the shared styling runtime when the host loads the exposed module. The app's own
entry already covers the standalone build; without the import in PartyStack the styles work
standalone and quietly do nothing federated. Jest has no CSS loader, so the copied config maps
that import to the stub. Without it the Party suite does not fail; it refuses to run.

Then the script that runs the accessibility files through the reporter:

for app in apps/list apps/party; do
  ( cd $app && npm pkg set 'scripts.test:a11y=jest --testPathPattern accessibility --reporters=default --reporters=@pokedex/a11y-testing/reporter.js' )
done

Both Jest configs point at the shared preset. Because it extends the React Native preset, the suites each app already had keep running, and the rule is to widen its allowlist rather than replace it. In outline, since the copied files carry more entries than this:

const preset = require('@pokedex/a11y-testing/jest-preset');

module.exports = {
  preset: '@pokedex/a11y-testing',
  transformIgnorePatterns: [
    `node_modules/(?!(${[...preset.uncompiledPackages, '@react-navigation'].join('|')})/)`,
  ],
};

Replacing that array is how a shared preset quietly stops being shared. It does not fail quietly, though: the styling stack ships ES modules, so Jest hits SyntaxError: Cannot use import statement outside a module and runs nothing at all. That is the good case. The trap is that the error names a file deep in node_modules and reads like a broken dependency rather than like a config line the app owns. Exporting the list makes widening the easy move.

Each suite covers only what its team composes, and the way to keep that honest is to render the team's own screens rather than the design system's components. Both files mount the real stack through the real store and the real navigator, the same harness the apps' existing tests use:

const store = configureStore({ reducer: rootReducer });
for (const member of party) {
  store.dispatch(addToParty(member));
}
await renderWithTheme(
  <Provider store={store}>
    <SafeAreaProvider initialMetrics={metrics}>
      <NavigationContainer>
        <PartyStack />
      </NavigationContainer>
    </SafeAreaProvider>
  </Provider>,
);

That is more setup than mounting a PokemonCard directly, and it is the difference between testing this app and testing somebody else's package. A suite that renders design-system components re-checks what the source already settled, which is exactly the duplication the source contract exists to remove.

So the Pokédex checks the rows its own query data produces, the states its screen can land in, and its party counter. The Party checks its grid: a filled slot is a button naming its Pokémon, the empty ones are named gaps rather than four identical silences, and removal is an accessibility action on the card rather than a second focus stop beside it.

expect(getByLabelText(/^Pikachu, number 025/).props.accessibilityActions).toEqual([
  { name: 'remove', label: 'Remove from party' },
]);

The ✕ badge is small (21 points, because h-6 is 1.5rem and NativeWind's rem is 14, so its hitSlop carries it to 45 rather than the 41 it had), and making it its own focus stop would double the number of things to swipe past on a full party. The design system hides it and exposes removal as an action instead, so a screen-reader user reaches it through VoiceOver's rotor or TalkBack's actions menu. The check is that the action exists at all, because a hidden control with nothing behind it is simply unreachable.

Rendering the real screen is also what turned the counter's second fault from a note into a fix. The Pokédex header shows "My Party" beside a count out of six, and that count changes when something is added from a screen away, without focus moving. A sighted user watches the number tick; a screen-reader user was told nothing, because the header was static text. That is the whole of SC 4.1.3, and it is now a live region with a label that spells the ratio out, because a bare "3/6" is left to how a given screen reader says it:

<Box
  accessible
  accessibilityLiveRegion="polite"
  accessibilityLabel={`My Party, ${partyCount} of ${MAX_PARTY}`}>

The Party's own header needs the same three props, and that is the cost of a fault living in app code twice over: two screens, two suites, and nothing that makes the second one look.

A test asserting that against a hand-written object would have proved nothing about the app. Against the rendered screen it fails if the props are removed, which is the only version worth keeping.

The report

One accessibility-report.md comes out of each suite, written by the reporter as the run finishes:

( cd packages/ui && npm run test:a11y )

The reporter reads the criterion out of each describe title, so WCAG 1.4.3 … is all the wiring there is. The design system's run opens like this:

# Accessibility report — ui

Automated coverage: **5 of 13** WCAG 2.1 A + AA criteria that a Jest suite can decide,
after 2 declared not applicable here.

## Violations (0)

None.

## Known findings (0)

None.

The exempt pair does not appear there. It has its own heading, because a threshold a project
chooses is not a result against a criterion, and filing one as the other is how a coverage
number stops meaning anything:

## Project bars

- **not held** — pairs held above what the criteria require · disabled button label
  on its fill (known: 2.02:1, exempt under 1.4.3 Incidental)

The denominator is where a coverage number is easiest to inflate, so it is built in two steps. The catalogue carries all 50 of WCAG 2.1's A and AA criteria and tags each one with the layer that can decide it: 15 a Jest process can, and the rest belonging to the device audit, the manual pass, or to nothing here at all, like the audio and video criteria in an app with neither. A suite then removes the ones it declares inapplicable, which is why the design system is measured out of 13. Those declarations live in an a11y-report.config.js at the suite root, and each carries a reason, whether the criterion was in the counted set or not. Nothing enforces that the reason is any good; it is there so a reviewer can disagree with it.

The touch-target work appears in the reports of the suites that do it, and never in that fraction. The design system's run says so in its own section:

## Checked beyond the counted scope

These ran and are reported, but they sit outside the WCAG 2.1 A + AA set the coverage
number is measured against, so they do not raise it.

- **WCAG 2.5.5** not in the A + AA catalogue — 4 checks

SC 2.5.5 is Level AAA, so counting it would inflate an A and AA figure. Dropping it silently would hide a check that ran. The report does neither.

That is roughly the artefact a paid accessibility scanner sells, generated from tests the team already owns.

What these checks cannot see

A green suite here proves less than it looks like it proves.

Layer	What it proves	What it cannot
Jest suite	token pairs, declared sizes, the name, role and state a control exposes	what a device paints, real traversal order, hit regions after clipping
Device audit	contrast as drawn, clipped targets, sizing on a real screen	whether a label reads well out loud
Manual pass	the actual experience, traversal order included	catching every regression, on every commit

The device audit is performAccessibilityAudit on iOS and the Accessibility Test Framework on Android; the manual pass is a person with VoiceOver or TalkBack.

Focus order sits with the manual pass, which is the honest answer to the third thing post 11 promised. A Jest suite can say that focusable elements are present. It cannot say what order a screen reader traverses them in, because that order comes out of layout on a real screen. Nor is the device layer a clean home for it: Android's Accessibility Test Framework has a traversal-order check and iOS's performAccessibilityAudit has no equivalent, and a criterion only one platform can automate is not one a report should claim. So it stays with the person driving the screen reader, which is where the catalogue tags it.

The layers are not a ladder where the top one contains the ones below it. The token matrix checks the pairs the design system composes, on the surfaces it composes them on, whether or not a screen shows a given pair today; a device audit checks what is on the screen it was pointed at, which is a different set and never the whole palette. A clean automated run is necessary and not sufficient, and the same is true of a clean device pass.

Run it

Every suite, including the ones that predate this post:

( cd packages/a11y-testing && npm test )
( cd packages/ui && npm test )
( cd packages/detail && npm test )
( cd apps/list && npm test )
( cd apps/party && npm test )
( cd apps/host && npm test )

The first line is the bar testing itself. A package that tells four workspaces what accessible
means should be able to prove its own helpers, and the cases in there are the ones earlier
versions got wrong.

Then the accessibility layer on its own, with the report:

( cd packages/ui && npm run test:a11y )
( cd packages/detail && npm run test:a11y )
( cd apps/list && npm run test:a11y )
( cd apps/party && npm run test:a11y )

No simulator and no dev servers. Every package was published as it was built, so nothing here republishes anything.

What you built, and what's next

One package now holds the accessibility bar for the whole federation, and five suites run against it: the bar's own helpers, the tokens and components in @pokedex/ui, the shared screen in @pokedex/detail, and each remote's own screens.

What came out of it divides by where the fault lived, and that division is the point. @pokedex/ui held eleven: two badge foregrounds below AA on their own fill, four more below it on the hero scrim, the back pill's glyph below the non-text bar on three of the eighteen heroes, two secondary-text lines failing in both themes, and two components that announced a failed load in silence. Add the retry button's touch target and the card badge's, and it is thirteen. All three apps took every one of them by a version bump, which is the whole argument for a design system stated as a number.

@pokedex/detail held three, and the host does not install it, so all three stopped at the two remotes: the Add button's target, the hero's dex number, and the sheet's two section headings.

Four could not travel at all, and they are the interesting ones. Two are the host's own tab labels, in the shell that owns no screens. The other two are the party counter: app code, the same header written twice, once in each remote, owned by no package. It carried one fault of each kind, a count that announced nothing and a numeral at 1.53:1 on its own pill. Each of those four had to be fixed where it sat, and two of them had to be fixed twice.

The faults that mattered more were in the checks. This post showed four: a helper that borrowed the bar for an axis nobody had declared, a matrix reading a constant instead of the token, the same matrix reading the wrong surface, and a marker that was only a string. More turned up afterwards, in the design system's suites and in the bar's own. A scrim guard in the design system compared two constants exported from the same module. In a clamp test the value never reached the ceiling it was clamping to. The bar's own use-of-colour helper read screen-reader metadata rather than the text on screen. And a target guard fell back to a number written in the test when its own pattern stopped matching. Every one of them now has a case that fails when the repair is taken out again, which is the only evidence a guard is real. A check aimed slightly beside the thing it names reports green, and goes on reporting green. Nothing in the output distinguishes it from a check that works.

Nothing stays open against a criterion. Five pairs did for five rounds, all of them the same secondary-text token, parked on the reasoning that no single darker value clears every surface. That was true and it was answering the wrong question: the design system is theme-aware, and the pairs took a themed class rather than a new token. One finding stays tracked and it is not a criterion result, because SC 1.4.3 exempts an inactive control's label. The report prints it under Project bars, counted nowhere.

The honest limit is the layer. This post builds the Jest layer and neither of the other two. The device audit harness is real work that has not been done here, and the manual VoiceOver and TalkBack pass is not automatable by design. This layer exists for the regression: the things you have already fixed staying fixed, on every commit, in every remote, against one definition.

Next: the host lends the remotes its native side. A navigation bridge launches a native screen from the Party tab and waits for its result.

Sources

WCAG 2.2, SC 2.5.5 Target Size (Enhanced) — Level AAA, 44 by 44 CSS pixels
WCAG 2.2, SC 2.5.8 Target Size (Minimum) — the AA criterion, 24 by 24 with five exceptions
WCAG 2.2, contrast (minimum) — 4.5:1 for normal text, 3:1 for large
WCAG 2.2, relative luminance — the formula, and the note recording the May 2021 change from 0.03928 to 0.04045
Apple Human Interface Guidelines: Accessibility — the current control-size table: 44 by 44 points as the iOS and iPadOS default, 28 by 28 as the minimum
Apple: UI Design Dos and Don'ts — the older page, "at least 44 points x 44 points"
Android accessibility help: touch target size — the 48dp guidance
jest-axe — the jsdom requirement and the disabled contrast checks
Directive (EU) 2019/882 — the European Accessibility Act, applied from 28 June 2025
EN 301 549 — the European standard that applies WCAG 2.1 to mobile apps
React Native Testing Library — the queries and matchers this builds on
nativewind — nativewind/test, shipped and undocumented
react-native-css-interop — the toHaveStyle matcher, and the rem this stack resolves against
react-native-module-federation — the companion repo, the build at the tag post-12-a11y-testing

The design system as a federated singleton in React Native

Warren de Leon — Tue, 08 Sep 2026 00:04:58 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 10 closed on a promise: the design system becomes a federated singleton, one UI package shared at runtime, so every remote renders the same components without shipping its own copy. This post keeps it.

The debt is real. Since post 4 every screen has styled itself with StyleSheet.create and hard-coded hexes, and the duplication now spans three apps and the view package: the same template greys sit in the list, the party and the detail view, and the same blue accent appears in the host's Refresh button and the detail's Add button. Four codebases, four copies of the same design decisions, and no way to change any of them in one place.

The fix applies two earlier patterns to pixels. Post 3 shared libraries as singletons so one copy serves every app. Posts 5 and 6 put packages at the seam so every side installs one definition.

@pokedex/ui does both. It packages gluestack-ui's copy-in components, styles them with NativeWind 4.2.6 and publishes them through the local Verdaccio registry. Module Federation then gives every remote the host's copy at runtime. This build uses @gluestack-ui/core on ^3.0.25, @gluestack-ui/utils on ^3.0.21 and Tailwind 3.4.19.

📊 Diagram: view it on warrendeleon.com

The seam now holds three packages, and they cross it differently. The contracts and the design system resolve to one copy at runtime, drawn as the host providing them. The detail package deliberately does not: each consumer keeps its own version pin, which has been its point since post 5. That contrast is the heart of this post.

A package for the pixels

Start from post 10's tag:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-10-two-backends

One honest boundary before the anatomy. The design system's source is more than a post can carry: thirteen copied gluestack components, token maps for eighteen types, eleven composed components. So this post's packages are pulled from the finished tag rather than typed in, and that includes the new versions of contracts and detail, because this post grows both (The detail finishes dressing says how). Fetch the reference copy once (Run it reuses it for the native chrome) and take all three packages:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-11-design-system /tmp/pokedex-ref
rm -rf packages/ui packages/contracts packages/detail
cp -R /tmp/pokedex-ref/packages/ui /tmp/pokedex-ref/packages/contracts /tmp/pokedex-ref/packages/detail packages/

packages/ui follows the anatomy posts 5 and 6 established: react-native-builder-bob builds an ESM lib/, "react-native": "./src/index.ts" ships raw source so Re.Pack compiles the same files the repo holds, publishConfig points at the local Verdaccio, and the files list adds two entries the earlier packages never needed: tailwind.preset.js and global.css.

The gluestack CLI copies component source into src/components/ui/. Copy-in means you own the source: your package publishes that code, and upstream updates do not arrive automatically. The companion keeps the thirteen primitives these screens use, from box to vstack.

One copy has a hidden dependency. heading imports @expo/html-elements, which the generated package does not declare. Add it to dependencies, or consumers fail on a package they did not install.

Above the primitives sit the tokens and composed components. tailwind.preset.js carries the brand and neutral colours plus type.<name> for all eighteen Pokémon types. The same values live in src/tokens/ for runtime code. Eleven components use them: ScreenContainer, PokemonCard, TypeBadge, LoadingState, ErrorState, InfoRow, StatBar, EmptySlot, BackPill, ThemeToggle and Toaster. A primitives.ts barrel keeps consumer imports on one package surface.

Two decisions belong with the tokens, and both fail quietly when they are left to the components.

Only literal class strings generate. A constructed `bg-type-${t}` is invisible to Tailwind's scanner, and the colour silently never ships. The token file spells out every class in literal maps (TYPE_BG_CLASS and friends) and exports lookup helpers, which keeps the whole palette in one auditable place.

The second is text contrast. Type colours need measured foregrounds, not a visual guess. White on the water blue measures 3.48:1 and on the psychic pink 3.41:1, below WCAG's 4.5:1 minimum for small text. Black clears 6:1 on both. textOnTypeClass() computes the higher-contrast choice once and every type-coloured surface uses it. A hard-coded black foreground would put the fighting-type hero at 1.7:1.

One kind of input could never have been typed in anyway: images. The theme toggle's moon and sun and the back pill's chevron ship as PNG files in src/assets, which came across with the copy, and the files list bundles them into the published package.

Publish it the way posts 5 and 6 did, install step and all:

( cd packages/ui && npm install && npm run build && npm publish )

Version 1.0.2 is the intended 1.0.0 API plus the patches later hardening passes added.

The detail finishes dressing

The finished detail needs data the earlier contract did not carry. Contracts 3.2.2 adds heightM, weightKg, abilities, stats and optional flavourText to PokemonDetail. It also adds types to PartyMember, so the party can tint cards without another request. parsePokemonDetail converts PokéAPI's units and normalises the flavour text once at the boundary.

Both remotes now fetch the species payload beside the Pokémon, and the list passes type data when it adds a member. The app-file sweep in Wiring a styling runtime into a federated build carries those edits. The new package source already came from the reference copy, so publish contracts and detail before the apps install them:

( cd packages/contracts && npm install && npm run build && npm publish )
( cd packages/detail && npm install && npm run build && npm publish )

@pokedex/detail 4.0.2 rebuilds the view around the design system: a type-coloured collapsing hero, a ringed sprite, flavour text, Info rows, Base Stats and the Add button. It is a major because it gains peers: @pokedex/ui, NativeWind and Reanimated become requirements on every consumer.

Its props do not change. The view still accepts { pokemon, loading, error, onRetry, onAddToParty, addDisabled, addLabel }, so both containers move to the new view with a version-pin edit. The largest visual change in the series reaches them through npm install.

The collapse is the screen's signature move, and it is worth seeing before the wiring section, because every colour in it is a token class resolved through the seam:

🎞️ Animated demo: watch it on warrendeleon.com

Wiring a styling runtime into a federated build

NativeWind's own docs support Metro; Re.Pack appears under community-driven solutions. From the other side, Callstack ships a first-party plugin, @callstack/repack-plugin-nativewind, version-locked to the installed Re.Pack (5.2.5 here). Reanimated needs the same treatment: Re.Pack detects the package and warns when ReanimatedPlugin is missing, so @callstack/repack-plugin-reanimated goes in beside it at the same version. Both halves are true, and this wiring is the plugin's documented path.

All three apps receive the styling dependencies. The two remotes also install detail 4.0.2 and contracts 3.2.2. Every app declares gluestack core and utils directly because the copied source imports them. Each app also pins react and react-dom to its React version, 19.2.3, so peer resolution cannot install a second React.

( cd apps/host && npm pkg set overrides.react=19.2.3 overrides.react-dom=19.2.3 && npm install nativewind@4.2.6 @gluestack-ui/core@3.0.25 @gluestack-ui/utils@3.0.21 react-native-reanimated@4.6.0 react-native-worklets@0.12.1 @pokedex/ui@1.0.2 @pokedex/contracts@3.2.2 && npm install -D tailwindcss@3.4.19 @callstack/repack-plugin-nativewind@5.2.5 @callstack/repack-plugin-reanimated@5.2.5 postcss@8.4.47 postcss-loader@8.1.1 autoprefixer@10.4.20 @module-federation/enhanced@2.9.0 @react-native-community/cli@20.2.0 @react-native-community/cli-platform-android@20.2.0 @react-native-community/cli-platform-ios@20.2.0 )

( cd apps/list && npm pkg set overrides.react=19.2.3 overrides.react-dom=19.2.3 && npm install nativewind@4.2.6 @gluestack-ui/core@3.0.25 @gluestack-ui/utils@3.0.21 react-native-reanimated@4.6.0 react-native-worklets@0.12.1 @pokedex/ui@1.0.2 @pokedex/contracts@3.2.2 @pokedex/detail@4.0.2 && npm install -D tailwindcss@3.4.19 @callstack/repack-plugin-nativewind@5.2.5 @callstack/repack-plugin-reanimated@5.2.5 postcss@8.4.47 postcss-loader@8.1.1 autoprefixer@10.4.20 @module-federation/enhanced@2.9.0 @react-native-community/cli@20.2.0 @react-native-community/cli-platform-android@20.2.0 @react-native-community/cli-platform-ios@20.2.0 )

( cd apps/party && npm pkg set overrides.react=19.2.3 overrides.react-dom=19.2.3 && npm install nativewind@4.2.6 @gluestack-ui/core@3.0.25 @gluestack-ui/utils@3.0.21 react-native-reanimated@4.6.0 react-native-worklets@0.12.1 @pokedex/ui@1.0.2 @pokedex/contracts@3.2.2 @pokedex/detail@4.0.2 && npm install -D tailwindcss@3.4.19 @callstack/repack-plugin-nativewind@5.2.5 @callstack/repack-plugin-reanimated@5.2.5 postcss@8.4.47 postcss-loader@8.1.1 autoprefixer@10.4.20 @module-federation/enhanced@2.9.0 @react-native-community/cli@20.2.0 @react-native-community/cli-platform-android@20.2.0 @react-native-community/cli-platform-ios@20.2.0 )

The overrides block is why those installs start with npm pkg set. gluestack pulls react-native-web and react-dom in as transitive peers, and their react ranges collide with the app's pinned react@19.2.3. Pinning both in overrides settles it. Reaching for --legacy-peer-deps instead hides the version mismatches a shared singleton needs you to see.

The last four pins update @module-federation/enhanced and the React Native CLI trio (the core package and both platform packages) to their current releases, which clear this stack's fixable npm audit advisories; the repo README records what remains and why. react-native-reanimated and react-native-worklets carry native code, so the host needs its pods refreshed before the Run it build: ( cd apps/host/ios && bundle install && bundle exec pod install ), the same convention the repo README uses. Who shares what explains why react-native-reanimated and react-native-worklets are here at all. Pin tailwindcss below 4. NativeWind 4's styling runtime, react-native-css-interop, declares a Tailwind 3 dependency, and npm's latest Tailwind is a 4.x that will not work here.

The per-app configuration, entry files and rebuilt screens come from the reference copy. This sweep makes the reader's tree match the tag:

for app in host list party; do
  cp /tmp/pokedex-ref/apps/$app/babel.config.js \
     /tmp/pokedex-ref/apps/$app/global.css \
     /tmp/pokedex-ref/apps/$app/index.js \
     /tmp/pokedex-ref/apps/$app/jest.config.js \
     /tmp/pokedex-ref/apps/$app/rspack.config.mjs \
     /tmp/pokedex-ref/apps/$app/tailwind.config.js \
     /tmp/pokedex-ref/apps/$app/tsconfig.json apps/$app/
done
cp /tmp/pokedex-ref/apps/host/App.tsx /tmp/pokedex-ref/apps/host/mf-modules.d.ts apps/host/
cp /tmp/pokedex-ref/apps/host/__mocks__/react-native-reanimated.js /tmp/pokedex-ref/apps/host/__mocks__/partyApp-styles.js apps/host/__mocks__/
cp /tmp/pokedex-ref/apps/host/__tests__/RemoteBoundary.test.tsx apps/host/__tests__/
cp /tmp/pokedex-ref/apps/list/src/ListStack.tsx /tmp/pokedex-ref/apps/list/src/PokedexScreen.tsx /tmp/pokedex-ref/apps/list/src/detailApi.ts /tmp/pokedex-ref/apps/list/src/typesApi.ts apps/list/src/
mkdir -p apps/list/__mocks__
cp /tmp/pokedex-ref/apps/list/__mocks__/react-native-reanimated.js /tmp/pokedex-ref/apps/list/__mocks__/styleMock.js apps/list/__mocks__/
cp /tmp/pokedex-ref/apps/list/__tests__/addGate.test.tsx /tmp/pokedex-ref/apps/list/__tests__/doubleTapAdd.test.tsx /tmp/pokedex-ref/apps/list/__tests__/parsePokemonDetail.test.ts /tmp/pokedex-ref/apps/list/__tests__/parsePokemonTypes.test.ts apps/list/__tests__/
cp /tmp/pokedex-ref/apps/party/src/PartyScreen.tsx /tmp/pokedex-ref/apps/party/src/PartyStack.tsx /tmp/pokedex-ref/apps/party/src/detailApi.ts /tmp/pokedex-ref/apps/party/src/styles.ts apps/party/src/
cp /tmp/pokedex-ref/apps/party/__tests__/partyStateReady.test.ts /tmp/pokedex-ref/apps/party/__tests__/partySelfRecovery.test.tsx /tmp/pokedex-ref/apps/party/__tests__/removeAnimatesBeforeCommit.test.tsx apps/party/__tests__/
mkdir -p apps/party/__mocks__
cp /tmp/pokedex-ref/apps/party/__mocks__/react-native-reanimated.js apps/party/__mocks__/
cp -R /tmp/pokedex-ref/scripts .
cp /tmp/pokedex-ref/README.md .

Babel gains NativeWind's JSX source, the Rspack config gains the plugin, and a three-line global.css holds the Tailwind directives. The interesting file is tailwind.config.js:

module.exports = {
  presets: [require('nativewind/preset'), require('@pokedex/ui/tailwind.preset.js')],
  darkMode: 'class',
  content: [
    './App.tsx',
    './src/**/*.{js,jsx,ts,tsx}',
    path.join(path.dirname(require.resolve('@pokedex/ui/package.json')), 'src/**/*.{js,jsx,ts,tsx}'),
    path.join(path.dirname(require.resolve('@pokedex/detail/package.json')), 'src/**/*.{js,jsx,ts,tsx}'),
  ],
  theme: { extend: {} },
  plugins: [],
};

Three wiring warnings live in that file and its neighbours, and each one fails silently if ignored.

Scan the packages' source. Tailwind generates a class only when it sees the literal string, and the design system's classes live in node_modules. The content globs must include the shipped source of @pokedex/ui and @pokedex/detail, resolved via require.resolve. Miss this and the breakage looks intermittent: a class the app also uses still works, and only the classes unique to the library vanish.

Import global.css in every exposed module, not just the entry. Federation loads the exposed module, never the remote's own index.js, so a global.css imported only at the entry works standalone and silently no-ops federated. ListStack.tsx imports it at the top for exactly this reason, and the party reaches it through the module described in Styles are a boot-time registration.

darkMode: 'class' is load-bearing. NativeWind's setColorScheme throws without it, and the One toggle, three bundles flip is built on that call.

Styles are a boot-time registration

The party's copy of that import moved one step earlier, and the reason is worth the detour.

Registering a stylesheet writes into the styling runtime every mounted component reads. When the party tab's module arrives during a lazy render, that write lands while the Pokédex's screens are on screen, and React says so in development: Can't perform a React state update on a component that hasn't mounted yet, with a component stack pointing into the list's bundle. Three of them, on the tab's first open. Nothing breaks. The screen paints correctly, the warning is a development-only log, and a reader who never opens the second tab never sees it.

It is still worth fixing, because the cause is now specific rather than mysterious. Post 8 recorded a warning of the same shape at boot and said plainly that it had not been traced. This one traces: import '../global.css' at the top of an exposed module runs during the render that loads that module. Bisecting confirms it. Comment the import out and the tab opens silently.

So the party's styles became a module of their own:

// apps/party/src/styles.ts
// The remote's styles as a module the host can preload, for the same reason partySlice is one:
// registering them is a side effect the styling runtime shares with every app already mounted.
import '../global.css';

It joins the exposes map beside the state module, and PartyStack.tsx imports ./styles rather than the stylesheet directly, so the standalone build still registers them:

exposes: {
  './PartyStack': './src/PartyStack.tsx',
  './partySlice': './src/partySlice.ts',
  './styles': './src/styles.ts',
},

The host then loads it in the effect that already loads the state module, one line above it:

import('partyApp/styles').catch(err => console.warn('party styles failed to load', err));

That extends post 8's rule by a second half. What a remote must register before it renders (its reducer, its styles) loads at boot; screens still load on demand. The Pokédex tab needs no such move for a reason worth stating: it is the first thing the host renders, so its styles register while there is nothing else mounted to disturb.

Who shares what

The shared map decision is the identity test from posts 3 and 6, asked three times with three different answers.

nativewind belongs in the shared map because its runtime holds a module-level style registry and colour-scheme state. Two copies let a remote register styles in a registry the host never reads. Re.Pack discussion #1032 records the same registry failure. Its accepted answer suggests deep-sharing react-native-css-interop/, later replies still report the problem, and PR #1242 closed without merging its accumulation approach.

The host provides the one stateful styling runtime. With NativeWind shared as an eager singleton and the Re.Pack plugin wired into each app, both remotes register styles in the registry the host reads. This build verifies that behaviour across both remotes and both colour schemes.

@pokedex/ui joins it as an eager host provider: one provider, one theme and one set of component instances. Build-time tools stay out of the runtime map. Tailwind and PostCSS never ship, while Zod carries values rather than process-wide identity. The four host entries are:

'@pokedex/ui': {
  singleton: true,
  eager: true,
  requiredVersion: pkg.dependencies['@pokedex/ui'],
},
nativewind: {
  singleton: true,
  eager: true,
  requiredVersion: pkg.dependencies.nativewind,
},
'react-native-reanimated': {
  singleton: true,
  eager: true,
  requiredVersion: pkg.dependencies['react-native-reanimated'],
},
'react-native-worklets': {
  singleton: true,
  eager: true,
  requiredVersion: pkg.dependencies['react-native-worklets'],
},

Reanimated and Worklets register native views and a worklet runtime once per process. When the list bundled another copy for the detail collapse, the app died at load with the same native view name registered twice. The host now provides one copy to every consumer.

And @pokedex/detail stays out on purpose. Per-consumer versioning is its feature: the skew ladder from post 5 still works after this post, and a list shipping detail 4.0.2 while the party lags on 3.x is a supported state, not a bug. Same test, opposite answer, both correct.

The greys collapse

The screens keep their structure. The list renders PokemonCard in a three-column FlatList, and the party uses the same card beside the design system's EmptySlot. App-level colour literals move behind shared tokens; only token definitions and translucent detail overlays retain raw values:

Before, per app	After, from the seam
`#2a75bb` in two apps' buttons	`bg-pokemonGreen`, one token
`#6b7280`, `#9ca3af`, `#f3f4f6` template greys	`text-darkGrey`, `text-midGrey`, `bg-offGrey`
`#eef2ff` / `#4338ca` badge colours in the list	`TYPE_BG_CLASS` per real type
`#fff` screens	`ScreenContainer` variants: `bg-offWhite` light, `bg-navy` dark

Two smaller changes come with the conversion. The detail now arrives as a push inside each tab's stack, with the design system's BackPill floating over the hero, so the tab bar stays put while a detail is open:

🎞️ Animated demo: watch it on warrendeleon.com

And post 6's header Refresh button becomes a pull gesture the list owns. The dispatch is unchanged (one invalidated tag, which both of post 10's endpoints provide), so the REST rows and the GraphQL badges refetch together from a gesture instead of a button:

🎞️ Animated demo: watch it on warrendeleon.com

One toggle, three bundles

ThemeToggle is a design-system component with no props: a press writes the colour scheme into the shared nativewind singleton, and each remote mounts it in its own header's right slot. The interesting part is what it does not do: it never talks to a remote. The scheme is module-level state inside the shared styling runtime, every dark: class in the runtime re-resolves on the write, and three independently shipped bundles repaint together. No doc promises that; it is verified in this build.

The chrome changes on the same write. Everything derives from the same observable: the host themes its NavigationContainer from useColorScheme(), the same subscription the classes use. An earlier cut of this build kept a separate piece of host state beside it, and the native navigation bars flipped almost half a second before the content's styling pass. One source of truth put every surface on the same update wave.

🎞️ Animated demo: watch it on warrendeleon.com

Feedback rides the same singleton

Party feedback uses the same shared package. toast() is a plain function in @pokedex/ui, while the host mounts the runtime's one Toaster above the tab bar. After dispatching an add, the list reads the store and reports what the owner did. Two fast taps at five members produce one “joined your party” message and one “Your party is full” message because the reducer decides the outcome.

The list never mounts the component that draws the capsule. It calls the shared presentation API, and the host's Toaster renders the result with the Pokémon's sprite and type colour.

🎞️ Animated demo: watch it on warrendeleon.com

The party's remove confirms through the same path, which is the ownership rule from post 6 carried into presentation: each write's owner owns its feedback. toast() also announces the message to the screen reader itself, so a caller cannot show the visual confirmation and skip the accessible one.

🎞️ Animated demo: watch it on warrendeleon.com

Now break it

The map earned its entries; prove it by removing one. In apps/list/rspack.config.mjs, delete the nativewind entry from shared, restart the list's dev server, and reload.

Nothing crashes. The app boots, the list renders, the sprites load, and the layout is quietly wrong: the grid's column wrappers lose their widths, so each card sizes to its own content and the three columns stop lining up between rows. The colours hold, and so do the badges and the type, which is what makes this failure easy to miss. The remote now bundles its own styling runtime. Its build compiles the remote's classes into a registry the shared components never read, and the widths are the part that goes missing on screen. The components from @pokedex/ui are unaffected, because their classes were compiled by the host's scan into the host's runtime.

Post 6's failure was loud, post 8's was silent, and this one is silent and partial: the screen still works, and its grid stops being the design system's grid. Put the entry back, restart, and the grid snaps into shape. A styling runtime is shared state, and shared state under federation is either a singleton or a bug.

Run it

Native assets still ship with the host binary. Copy the tab icons, app icon, launch ball, Nunito fonts and native configuration from the companion. The ios/Host copy carries the icon catalogue, launch storyboard and app delegate. Copy project.pbxproj too, because Xcode renders the loose splash images only when the project lists them as resources. The final command links the typefaces:

cp -R /tmp/pokedex-ref/apps/host/src/assets apps/host/src/
cp -R /tmp/pokedex-ref/assets .
cp /tmp/pokedex-ref/apps/host/react-native.config.js apps/host/
cp /tmp/pokedex-ref/apps/list/react-native.config.js apps/list/
cp /tmp/pokedex-ref/apps/party/react-native.config.js apps/party/
cp -R /tmp/pokedex-ref/apps/host/ios/Host apps/host/ios/
cp /tmp/pokedex-ref/apps/host/ios/Host.xcodeproj/project.pbxproj apps/host/ios/Host.xcodeproj/
cp -R /tmp/pokedex-ref/apps/host/android/app/src/main/res apps/host/android/app/src/main/
( cd apps/host && npx react-native-asset@2.3.0 )

Verdaccio is already running from the publish steps, and the three packages are published. Start the three dev servers, each from its own terminal:

( cd apps/list && npm run start:remote )

( cd apps/party && npm run start:remote )

( cd apps/host && npm start )

Then build and launch the host app once, so the new app icon and asset catalogue compile in:

( cd apps/host && npm run ios )

Open the Pokédex tab for the three-column card grid, tap a Pokémon for the finished detail, add it to the party and watch the confirmation rise, then flip the header toggle to watch every surface, both remotes and the chrome included, change scheme on one press. The whole loop, splash to empty party, looks like this:

🎞️ Animated demo: watch it on warrendeleon.com

What you built, and what's next

One design system and one styling runtime now serve every remote. The remotes import @pokedex/ui as a package, while federation resolves it to the host's copy. A shell release can re-skin them without rebuilding each remote, provided the component API remains compatible.

The native boundary remains. react-native-svg ships a native module, and native code cannot arrive through federation. Fonts reach the same boundary for a different reason: the binary must contain and register each typeface at build time.

The companion makes both cases visible. The tab icons are plain tinted images, the Nunito faces are linked into the host binary, and the launch ball is a storyboard asset.

Next: accessibility across the seam, a shared testing package that checks touch targets, contrast and focus order in remotes the host only meets at runtime.

Sources

gluestack-ui — the copy-in component architecture; "you copy, paste, and own your components"
NativeWind — the className runtime, and the other-bundlers page that lists community solutions
@callstack/repack-plugin-nativewind — the first-party plugin this post wires
@callstack/repack-plugin-reanimated — the Reanimated transform Re.Pack asks for by name
Tailwind v3: content configuration — scanning your own component library's source
callstack/repack discussion #1032 — a remote's styles clobbering the host's registry; still open upstream
callstack/repack PR #1242 — the closed accumulation attempt; this build's singleton result is its own evidence
WCAG 2.2, contrast (minimum) — the 4.5:1 bar the type-colour tokens are computed against
react-native-module-federation — the companion repo, the build at the tag post-11-design-system

Two backends, one client? RTK Query vs Apollo in React Native

Warren de Leon — Mon, 31 Aug 2026 00:04:31 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 9 closed on a promise: the stack stays the same and the backend splits in two, REST for the list, GraphQL for the type badges, one client and one cache. This post builds it.

The question mark in the title is deliberate. During the transition, with a GraphQL backend arriving while REST is still live, one client wins almost regardless of which one it is, and if your app already runs RTK Query that settles it. At the destination, with GraphQL everywhere, the answer turns on two things you can check against your own app: whether you have a federation constraint, and whether your schema is relational enough that a normalised cache earns its keep. A normalised cache stores each entity once, one Pokémon in one slot, so every view that references it reads the same copy. This series has federation, so RTK Query stays the pick here. Change the context and the answer changes, and this post says where.

📊 Diagram: view it on warrendeleon.com

The left shape is the build: REST and GraphQL feeding one baseApi cache under one tag graph, with the host's Refresh button untouched. The right shape is two clients with two caches and no edge between them. That missing edge is what this post is really about.

A second backend arrives

The API team stands up GraphQL. For screens that need related data it can replace several round trips with one, which is where the speed-up comes from rather than from the protocol itself, and it is where the backend is heading. REST is not going away this quarter, or the next. For a while, often a long while, both are live, and every screen is served by one or the other.

The hazard is running two data-fetching clients at once, whichever two you pick. Two clients keep two caches, and the two do not coordinate on their own. A mutation that goes out over GraphQL updates the GraphQL cache, and the update never reaches the REST cache holding the same record. The user edits a Pokémon on the screen served by GraphQL, switches to the list served by REST, and sees the old value. No exception, no failed request, no warning. Just a screen that is quietly wrong until something forces a refetch. Mid-cutover, when the two backends overlap most, is exactly when it does the most damage.

So the transition question is how few caches to run, and the cheapest answer is one.

One slice, two protocols

RTK Query makes one cache serve both protocols, in the slice this series has run since post 6. Start from post 8's tag:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-08-client-state

The list already fetches its rows over REST. It gains a second server-state need, a type badge on each row, served over GraphQL. Two dependencies first, in the list remote only. graphql stays on 16 because graphql-request declares a peer range of 14 to 16 while npm's latest is 17:

( cd apps/list && npm install graphql@16.14.2 graphql-request@7.4.0 )

Then the endpoint, in the same api slice:

const typesApi = baseApi.injectEndpoints({
  endpoints: build => ({
    getPokemonTypes: build.query<Record<number, string[]>, void>({
      async queryFn() {
        try {
          const raw = await request(GRAPHQL_URL, POKEMON_TYPES);
          return { data: parsePokemonTypes(raw) };
        } catch (err) {
          return {
            error: {
              status: 'CUSTOM_ERROR',
              error: err instanceof Error ? err.message : 'Invalid GraphQL response',
            },
          };
        }
      },
      providesTags: ['PokemonList'],
    }),
  }),
});

export const { useGetPokemonTypesQuery } = typesApi;

An api slice has exactly one baseQuery, and the list's is fetchBaseQuery on the REST base. A second protocol against a different URL comes from a queryFn, which RTK's own docs list for "one-off queries that use a different base URL". graphql-request posts the query, and the same file carries what the excerpt leaves out: the bounded, ordered GraphQL query itself, the Zod schema that polices ids and type names, parsePokemonTypes, and the screen integration. Rather than print all of it, land your tree on the finished state:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-10-two-backends /tmp/pokedex-ref-10
cp -R /tmp/pokedex-ref-10/. .

The response is validated with its own Zod schema at the seam the REST list already guards, held constant so the comparison swaps only the protocol. The schema lives in the list app rather than the contract package, because a data definition travels with the domain that owns it (post 7's rule).

PokéAPI's GraphQL lives at graphql.pokeapi.co/v1beta2. The older v1beta schema is retired, and with it the pokemon_v2_ field prefix that fills every pre-2025 tutorial. Asking for pokemon_v2_pokemon today returns field 'pokemon_v2_pokemon' not found in type: 'query_root'. The working shape is the unprefixed one, checked live against the endpoint while writing this.

Two things stay deliberately absent. There is no contracts bump: the endpoint injects into the existing baseApi, and it declares the tag the list already owns. And graphql-request stays out of the Module Federation shared map, exactly as Zod does. It is a value-only library with no instance identity to share, so it rides as the list remote's own dependency. Which protocol served a row stays the remote's private business, invisible to the host and to every other remote.

PokéAPI's GraphQL is rate-limited to 100 calls an hour per IP, where REST is fair-use only. RTK Query's caching absorbs it in normal use. A run of cold reloads can still hit the cap, and a 429 mid-build is the limit, not a bug.

One tag across the cutover

The host's Refresh button has dispatched invalidateTags(['PokemonList']) since post 6, and it holds no reference to either endpoint. Both the REST list and the GraphQL types query provide 'PokemonList', so one press refetches both. React Native DevTools' Network panel shows it happening: one tap lands both requests together, and the v1beta2 preview shows the type data arriving over GraphQL.

That is the transition thesis in one tag: whichever client you keep, keep one. Nothing crosses automatically, though. A mutation clears the other protocol's cache when it names the tag they both provide, and only then; the shared graph is what makes that possible, not what performs it.

The same race is visible on the device: on a cold start the REST rows land first, and the GraphQL badges arrive a moment later as each query fills the shared cache:

🎞️ Animated demo: watch it on warrendeleon.com

The badges also degrade quietly. Point the GraphQL endpoint at an unreachable host and the rows still render, the badges are simply absent, and nothing moves on the screen.

The badges make GraphQL's own pitch concrete too. Types over REST would mean 151 detail calls, one per row, because the list endpoint returns only names and URLs. Over GraphQL it is a single query. Call that what it is, client request fan-out rather than N+1: the classic problem describes a backend repeating a data access per row, while this is one client making a request per row because the endpoint gives it nothing else. Fewer round trips is the win, and it is a point for the protocol rather than for either client.

What Apollo does that this can't

RTK Query treats a GraphQL response as data to cache by endpoint, the same as any REST payload. Apollo does something RTK Query does not attempt: with its default InMemoryCache it normalises. Each object with a __typename and an id gets one slot in the cache, and every query that references it reads that slot. A mutation whose response carries the same type and id updates the entity everywhere it appears, with no refetch.

That is real, and it is the honest reason to reach for Apollo. It is also narrower than the pitch. Auto-consistency covers modifying an entity already in the cache. It does not cover growing a list. In Apollo's own words, "a newly cached object isn't automatically added to any list fields that should now include that object", so a new row still needs an update function or a refetch.

The rest of Apollo's case holds up on its own terms. Fragment colocation lets a component declare the fields it needs and compose them upward by plain template-literal interpolation, with no build step; code generation is optional, and earns its place when you want typed results. Cache redirects can serve a detail view straight from data a list already fetched, but only when every field the detail query asks for is already in the cache. One extra field and the whole query hits the network. Subscriptions and @defer are supported, and @defer needs an incremental-delivery handler plus a streaming-fetch polyfill on React Native, so it is "supported, with setup" rather than free.

And the schema matters more than any of this. PokéAPI's own shape, Pokémon referencing types, abilities, species and evolution chains, with the same entities reused across many queries, is exactly the relational shape where normalisation pays for itself. On this data, Apollo's cache is the better fit, and pretending otherwise would be the strawman this series avoids. (Relay sits in the same family. urql belongs there only once you add Graphcache: its default document cache stores whole responses by query, closer to RTK Query's model than to Apollo's. The trade-offs in Choosing are about the normalised family, not any one library.)

What federation does to the choice

Start with the part that surprises people. Apollo has no injectEndpoints, and it needs none. An operation is a document executed against a client, not an artifact registered in a store, so any remote can ship its own queries against a shared client with zero registration machinery. A remote can even extend the cache at mount through cache.policies.addTypePolicies, which is documented public API. There is no official micro-frontend guide (an unanswered community thread and one customer story are the whole record), but the cache API happens to allow it. On the runtime-extensibility axis post 9 cared about, Apollo is not behind.

It also does not share TanStack's context problem. Apollo caches a single React context on the React instance itself, keyed by a well-known symbol, precisely so two copies of the library cannot hand you divergent contexts. The "no client in context" error fires only when React itself is duplicated. The singleton case for @apollo/client under federation is one cache instance and no version skew between the client and its hooks, not the context split.

Federation still tips the choice in two places: the tag graph and the transition. The one tag that refetches across remotes, and across two protocols, is coordination RTK Query has by construction and Apollo leaves to convention. And adopting Apollo mid-cutover means standing up a second cache next to the RTK Query one you already run, the exact two-cache shape from the start of this post, for the length of the migration. Apollo Client 4 also makes rxjs a required peer and moves its React exports, so the bundle gains a new dependency rather than swapping one.

<p>RTK Query</p>
<ul>
  <li><strong>Cache model:</strong> by endpoint, refetch on invalidate</li>
  <li><strong>Cross-protocol invalidation:</strong> one shared tag graph, built in</li>
  <li><strong>Adding queries from a remote:</strong> <code>injectEndpoints</code> at runtime</li>
  <li><strong>Relational, entity-reuse schema:</strong> refetches what it already had</li>
</ul>


<p>Apollo</p>
<ul>
  <li><strong>Cache model:</strong> normalised by <code>__typename</code> + id, patch in place</li>
  <li><strong>Cross-protocol invalidation:</strong> per-client; a second cache to coordinate</li>
  <li><strong>Adding queries from a remote:</strong> documents against the client; nothing to register</li>
  <li><strong>Relational, entity-reuse schema:</strong> the cache pays for itself</li>
</ul>

Choosing

No absolute winner, so read down to the case that fits your app.

Transition, both backends live: run one client. If the app is already on RTK Query, and this series is, that decides it. One cache, one tag, no two-cache staleness to police, and it is the common case.

Destination, GraphQL everywhere, with a federation constraint and shared coordinated state: RTK Query stays. The honest price is living without normalisation: tag invalidation refetches where Apollo would patch in place, and updateQueryData covers the few spots where a hand-patched update is worth it. You trade some round trips for one cache and one tag graph across independently shipped remotes.

Destination, GraphQL everywhere, a relational entity-heavy schema, and no federation constraint: Apollo, plainly. The normalised cache is the point of a GraphQL client, and without federation pulling the other way, that is the reason to adopt it. No hedge.

The signals to watch for are two specific days. The day you notice most of your invalidations refetch data the cache already held: normalisation would have saved those round trips. And the day the second backend goes live and two caches disagree on screen with no error to explain it. The first is a nudge toward Apollo. The second is the reason to run one client, and only one, all along.

Next: the design system becomes a federated singleton, one UI package shared at runtime, so every remote renders the same components without shipping its own copy.

Sources

RTK Query: customising queries — queryFn as an inline baseQuery, and the GraphQL baseQuery example
RTK Query: automated re-fetching — providing and invalidating by tag
Apollo: caching overview — normalisation by __typename and id
Apollo: cache redirects — serving a query from the cache, and the all-fields-present rule
Apollo: @defer — incremental delivery and its setup
PokéAPI GraphQL — the v1beta2 endpoint and the 100-calls-per-hour limit
graphql-request — the fetch-based client the queryFn uses
react-native-module-federation — the companion repo, the build at the tag post-10-two-backends

State stacks under federation: the same React Native app built twice

Warren de Leon — Mon, 24 Aug 2026 00:09:59 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 8 ended by promising this one: the same app rebuilt on TanStack Query and Zustand, the stack most React Native teams reach for first. That build now exists, on a branch cut from post 8's tag.

The rules I set myself: same three apps, same installed detail package, same feature set (the Pokédex list, the detail with its capped Add button, the party grid with remove, the live "My Party 3/6" counter), and no change the state stack did not force. The finished twin looks the same on the simulator, screen for screen, which is the control this comparison needs.

The verdict, before the proof. Both stacks build this app well. The TanStack and Zustand version has fewer moving parts, and for adding server state from a remote it is the more federation-friendly of the two: nothing to register, nothing to inject. Redux Toolkit buys two narrow things: a store that grows at runtime, and a closed set of writes. They matter only when separately deployed teams share live client state with rules that have to hold. If your app never reaches that point, the lighter stack wins and most of this argument will not apply.

📊 Diagram: view it on warrendeleon.com

The arrows run into the contract on the Redux side and out of it on the twin: Redux lets the remotes add to the seam at runtime, and this branch has them consume what the seam already ships. @pokedex/detail sits in both halves at the same version, because it is the same package, unchanged.

Server state: nothing to inject

TanStack Query's model is decentralised, and that is its best argument here. There is no central API object, no registration step, no build-time list of what exists. Any component in any bundle calls useQuery with any key against the shared client. A remote shipped a year after the shell can add server state to the running app by calling a hook.

A claim you will meet says TanStack needs every query key registered at the shell's build time. It is false. A key is a plain array named at the call site, so a remote shipped long after the shell registers its own keys at runtime, against the shared client, with nothing to inject. If anything, that is the more decentralised model.

Post 8 needed baseApi.injectEndpoints, one shared instance, and the middleware that runs its cache. The list app's data access on this branch is a fetch and a hook:

// apps/list/src/listApi.ts
async function fetchPokemonList(): Promise<PokemonSummary[]> {
  const res = await fetch('https://pokeapi.co/api/v2/pokemon?limit=151');
  if (!res.ok) {
    throw new Error(`PokéAPI responded ${res.status}`);
  }
  return parsePokemonList(await res.json());
}

export function usePokemonList() {
  return useQuery({ queryKey: pokemonKeys.list(), queryFn: fetchPokemonList });
}

parsePokemonList is imported from the contract and is byte-identical to post 8's. The Zod parsing, the model, the shapes: all of it survives the swap, because the data model belongs to the domain rather than to whichever library is holding the cache.

Sharing one client across separately built bundles is supported, with a caveat. The v5 migration guide's answer for micro-frontends is to pass a queryClient to a hook or a provider, replacing v4's custom context. That is a paragraph in a migration guide rather than a chapter on federation. The failure modes in React Native are the singleton ones this series has met before: two copies of @tanstack/react-query give you "No QueryClient set", two copies of React give you null hooks.

The cost lands somewhere else. RTK's injected endpoints extend one typed surface, so a team adding an endpoint sees the whole API and the tag graph it shares. TanStack's coordination is a string array. My answer is the contract package again: the key factory ships beside the client, so a rename is a version bump every consumer sees.

// packages/contracts/src/query.ts
export const queryClient = new QueryClient({
  defaultOptions: { queries: { staleTime: 60_000 } },
});

export const pokemonKeys = {
  all: ['pokemon'] as const,
  list: () => [...pokemonKeys.all, 'list'] as const,
  detail: (id: number) => [...pokemonKeys.all, 'detail', id] as const,
};

That is a recommendation, not documented practice. Key factories are established community practice for key sprawl at scale rather than an answer the official docs prescribe, and nothing in either addresses two teams owning keys under one prefix.

Post 8's endpoint-name collision has a quieter mirror here. On RTK, two apps injecting an endpoint called getPokemonDetail had to declare the collision with overrideExisting, and load order picked the winner. On TanStack, two apps calling useQuery with pokemonKeys.detail(1) share one cache entry, because keys compare by value. Nothing is registered, so nothing collides. Open Bulbasaur in the Pokédex and open it again from the Party tab, and the second screen renders from cache.

Whether a request follows is a default worth knowing: left on its defaults, TanStack marks cached data stale immediately (staleTime: 0), so a second observer mounting on the same key renders the cache and fires a background refetch. The staleTime: 60_000 on the client above (a minute, matching how long the Redux build keeps an unsubscribed cache entry) is what makes the remount cost no second request, so the two builds answer it the same way. The bad version of the shared entry is two teams whose queryFns have drifted, where the data depends on which screen the user opened first.

One small thing the shell gave up. Post 8's baseApi carried the base URL for every consumer. Here each queryFn fetches whatever it likes, and the host has no say in where a remote's data comes from.

Invalidation: a prefix is a promise

The host's Refresh button is host chrome that reaches into a remote's data without importing any of it. Post 8 dispatched invalidateTags(['PokemonList']). The twin:

<Pressable
  onPress={() => queryClient.invalidateQueries({ queryKey: pokemonKeys.all })}
  hitSlop={12}
  style={styles.refresh}
  accessibilityRole="button"
  accessibilityLabel="Refresh Pokédex">
  <Text style={styles.refreshText}>Refresh</Text>
</Pressable>

Query filters match by prefix, and only an exact filter narrows to one key, so everything the factory builds under ['pokemon'] goes stale at once and any mounted query refetches. The prefix is the whole agreement.

I compared these two models in tags vs query keys, and that argument holds here. Federation adds one thing: the two sides are separately deployed bundles that never sat in the same build. A tag is a value declared in a shared list; a key prefix is string equality across code that ships on different days. Putting the factory in the versioned contract turns the convention back into something a compiler and a release process can see.

Client state: the store moves back to the shell

This is where the two designs differ most.

In post 8 the party app created the party's state, owned it, and injected it into a store the host had already built. combineSlices exists for exactly that, and the slice arrived at runtime from a bundle the shell knew nothing about.

Zustand has no equivalent to that injection step. It creates stores dynamically without any trouble, so a remote can bring a store to a running app; what it has no built-in answer for is folding one into an existing store the way inject does. I do not read that as an oversight: Zustand's natural federated answer is several independent stores, one per remote, with no machinery at all. That answer works until a piece of state has to cross a module boundary, which is the case this whole series is about.

So the store ships in the contract package:

// packages/contracts/src/partyStore.ts
export const partyStore = createStore<PartyState>((set, get) => ({
  members: [],
  add: member => {
    if (get().members.length >= MAX_PARTY) return; // the cap lives with the owner's action
    set(state => ({ members: [...state.members, { ...member, uid: uid() }] }));
  },
  remove: id => set(state => ({ members: state.members.filter(m => m.uid !== id) })),
}));

createStore from zustand/vanilla, because the contract holds no React. Consumers subscribe with useStore(partyStore, selector).

The ownership inversion is the honest cost. The party app no longer writes the party's rules; it reads state that arrives in a package it installs. Its partySlice.ts is deleted, and so is the ./partySlice entry in its Module Federation config, so it exposes one module again instead of two. On the host side, src/store.ts is gone, the boot import that loaded the party's state module is gone, and the ambient declaration that typed it went with them.

Those deletions are the trade. Post 8 spent a section on a dispatch that vanishes because the slice's owner had not loaded yet, and it took a boot import, a readiness marker and a gated button to close that window. Here the failure cannot occur: the state exists as soon as anything imports the contract. The price was paid earlier, as a release. Every new piece of shared state is a new version of @pokedex/contracts that every app installs: a deploy on the web, an App Store cycle on mobile. Neither stack removes the coordination; they move it to a different day.

The component package is the control group. @pokedex/detail 3.1.0 is untouched: same version, same file, installed by both apps, wired to a Zustand action on one branch and a Redux action creator on the other. Worth being exact about what Redux matches on, because the comparison rests on it: a reducer recognises a closed set of action-type strings, so the two sides agree on party/add, not on a privileged creator object. A view that renders what it is handed does not care which library computed it. That is the payoff of the library rule from post 6.

Ownership: setState from anywhere

The cap is a rule the party owns, and on this branch it lives inside add. Every write that goes through add is capped. setState is public on every Zustand store, and it does not go through add.

The whole demonstration sits in the list app's detail container, next to the legitimate wiring:

// apps/list/src/ListStack.tsx — a module with no business writing this state
const bypassTheCap = () =>
  data &&
  partyStore.setState(s => ({
    members: [
      ...s.members,
      { uid: `bypass-${s.members.length}`, id: data.id, name: data.name, spriteUri: data.spriteUri },
    ],
  }));

No type error. No warning. Nothing the owning team can review. The party fills to six, the Add button disables itself, and a long-press on the same screen puts a seventh Pokémon in a six-slot party:

🎞️ Animated demo: watch it on warrendeleon.com

The long-press is only there so the bypass can be filmed. The call is the point.

Watch the header. The party's grid renders six slots, so the seventh member has nowhere to appear, and the counter reading 7/6 is the only surface that shows it. The owning team's own UI cannot display the state a foreign module just wrote.

Redux permits foreign writes too: any module can dispatch anything. What differs is that a slice declares every write the owner will honour, so an action the owner never declared changes nothing, and the legitimate mutations are readable in one file. A Zustand store exposes the state itself, and a rule inside a function binds only the callers who use that function.

Inside one team this is a non-issue. Everyone knows setState is there, code review catches it, and the convention holds because the people holding it sit together. The moment the writer and the owner are different teams on different release schedules, a convention is what you have in place of a boundary.

Choosing

There is no absolute winner. The deciding factor is who is allowed to write what.

One team owns all the state. TanStack Query and Zustand. Fewer concepts, less ceremony, nothing to inject, and setState is a convenience rather than a hole.
Independent teams, shared server cache, no shared client state. Still TanStack. Share the client as a singleton, put the key factory in a versioned contract, and you have the coordination you need.
Independent teams writing each other's client state, with rules that must hold. This is the case Redux Toolkit's weight is for: a store that grows at runtime and a closed set of writes per slice.
Mobile, with a slow release cycle. Weigh the shape of the change. On the Zustand branch every new piece of shared state is a contract release, and on mobile a release waits on App Store review.

The signal to watch for is the day a second team needs to write state the first team owns. After that day, the question is whether you would rather coordinate through a type or through a convention.

The twin is on its own branch, cut from post 8's tag, at post-09-tanstack-zustand. It is a fork, not a step forward: the series carries on from post 8 on main.

Next, the other half of the comparison. The stack stays the same and the backend splits in two: REST for the list, GraphQL for the type badges, one client, one cache, two teams.

Sources

TanStack Query: migrating to v5 — the micro-frontend answer, passing a queryClient in place of a custom context
TanStack Query: query filters — prefix matching, and exact
TanStack Query: query keys and effective query keys — key factories at scale
Zustand: createStore and useStore — the vanilla store and its React subscription
Redux Toolkit: combineSlices and RTK Query code splitting — what the other branch relies on
react-native-module-federation — the companion repo, at the tag post-09-tanstack-zustand

Client state across the seam: remotes that bring their own slices in React Native

Warren de Leon — Mon, 17 Aug 2026 00:09:56 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

Post 6 ended on an honest limitation: close the app and reopen it, and nothing you did survives. No party, no favourites, no memory. Everything crossing the seam so far has been server state: data PokéAPI owns, held in a cache every module shares. The app itself owns nothing yet.

This post gives it something to own: the party of six. Client state has no server behind it and no cache to refetch. It lives in a Redux slice, and under federation a slice raises the question this whole series circles: who owns it, and how do other features touch it without touching its owner? The ownership essay answered in principle. This post answers in code.

The shape we're building:

📊 Diagram: view it on warrendeleon.com

Hold one idea in your head: everyone shares the cache, but a client-state slice has exactly one owner. The party app owns the party. Everything another module needs (one action, one read shape, one cap) crosses through the contract, and near the end we dispatch into the slice before its owner has loaded, on purpose, to watch what Redux does with an action nobody is listening for.

Carry on from your own post 6 code if you built along. Otherwise, start from its finished state:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-06-shared-store

Who owns client state?

Two kinds of state now live in this app, each with a different owner, and between them sits the interaction that crosses.

The server cache is everyone's. Post 6 built it: one baseApi in the contract, one store in the host, endpoints injected by whoever owns the data. No app owns a cache entry. The data belongs to PokéAPI and the cache is only holding a copy, which is why any module may read it.

Private state has one owner and stays inside it. Which members the party holds, how removal works, what the cap means: all of that is the party app's business, in a slice nothing else imports.

The crossing interaction is the narrow strip between them. The Pokédex needs to add a member to a party it does not own, and its header wants to show "My Party 3/6" for state it cannot see. Those crossings get typed, named, versioned and put in the contract, because the rule from the ownership essay holds here too: apps never depend on each other. Apps depend on contracts.

That taxonomy decides everything else in this post. What follows is just each row of it, built.

The wall, and the reducer moves

The party's slice has to join the running store, and Redux Toolkit (RTK) has an API for exactly this: combineSlices builds a reducer with an inject method, and a slice injected at runtime starts reducing from that moment on. So the party app needs to call inject on the reducer object the host's store actually wired in.

Post 6's host built that reducer inline:

// apps/host/src/store.ts, in post 6
export const store = configureStore({
  reducer: combineSlices(baseApi),
  middleware: getDefaultMiddleware => getDefaultMiddleware().concat(baseApi.middleware),
});

There is nothing to reach. The reducer is an expression inside the host's source, never exported, and even an export would not help: apps don't import apps. A copy is worse than useless: combineSlices(baseApi) in the party app builds a second reducer that no store runs, and injecting into it changes nothing on screen.

This is the identity argument from post 6, third time around. baseApi moved to the contract because a consumer can only inject endpoints into the same instance the store wired. The root reducer moves for the same reason, one file over. packages/contracts/src/store.ts:

import { combineSlices } from '@reduxjs/toolkit';
import { baseApi } from './api';

export const rootReducer = combineSlices(baseApi);

And the host's store slims to an import:

// apps/host/src/store.ts
import { configureStore } from '@reduxjs/toolkit';
import { baseApi, rootReducer } from '@pokedex/contracts';

export const store = configureStore({
  reducer: rootReducer,
  middleware: getDefaultMiddleware => getDefaultMiddleware().concat(baseApi.middleware),
});

The host still owns the store: the middleware, the Provider, the wiring. The contract package now owns the reducer the same way it owns the api instance. Because contracts is a federation singleton, rootReducer is one object in the whole runtime, and a slice injected by an app built months after the shell lands in the reducer the shell is already running.

The contract carries the crossing

Now the taxonomy's middle row. The interactions that cross an app boundary go in a new packages/contracts/src/party.ts, and it is short on purpose:

import { createAction, nanoid } from '@reduxjs/toolkit';

export const MAX_PARTY = 6;

export interface PartyMember {
  uid: string;
  id: number;
  name: string;
  spriteUri: string;
}

export const addToParty = createAction(
  'party/add',
  (member: Omit<PartyMember, 'uid'>) => ({ payload: { ...member, uid: nanoid() } }),
);

export const partyStateReady = createAction('party/stateReady');

export interface PartySliceShape {
  party?: { members: PartyMember[] };
}

addToParty is the one action anything outside the party dispatches. The contract owns the action's shape; the party's reducer owns what it means. The prepare callback stamps each member with a nanoid() (shipped inside RTK, no new dependency), so the reducer stays pure and two copies of the same Pokémon stay distinguishable. Duplicates are allowed by design: a party of six Magikarp is a valid life choice, and the uid is what tells them apart when one gets removed.

MAX_PARTY sits at the seam because every surface that reflects the rule has to read the same number: a disabled button in one app, a counter in another, the guard in the owner's reducer.

partyStateReady is the odd one out: no reducer case handles it, and nothing about the party changes when it is dispatched. It exists for the boot sequence, and the section on loading state modules shows the one useful thing it does.

PartySliceShape is the read side, and the optional marker is the design, not defensiveness. The slice is injected at runtime by a module the reader does not control, so at the moment a foreign module reads, state.party may not exist yet. Readers write s.party?.members ?? [] and render something honest either way. Typed alternatives exist (RTK's withLazyLoadedSlices can thread the possibly-absent slice through declaration merging), but the tolerant shape teaches the situation rather than hiding it, and the Now break it sabotage depends on you understanding it.

Notice what is absent. The party will also have a remove action, and it appears in no contract, because nobody else dispatches it. The contract carries what crosses, nothing more; an entry nobody consumes is a liability with a version number.

Both new files are additive, so the version is a minor; the tag carries 3.1.3, the minor plus the same hardening patches the 3.0.x line took. Publish:

cd packages/contracts
npm install && npm publish

+ @pokedex/contracts@3.1.3

The host and the list both sit on ^3.0.0, and here the lockfile matters more than the caret. A plain npm install changes nothing: the lockfile pins 3.0.3, and install honours the lockfile even though the caret would accept 3.1.3. Walking a caret forward is its own command:

( cd apps/host && npm update @pokedex/contracts )

No package.json edit, one lockfile line moved. The pin only gets touched when a consumer crosses a major. One consumer is about to.

The owner

The party app has been the series' control group: contract on ^1.0.0, detail on ^1.0.0, no store access, a static grid of six empty slots. Growing a slice ends that on every front, and the adoption is a deliberate edit because two majors is a real distance. apps/party/package.json:

"@pokedex/contracts": "^3.1.0",
"@pokedex/detail": "^3.1.0",
"@reduxjs/toolkit": "^2.12.0",
"react-redux": "^9.3.0"

npm install, and the build breaks immediately, in the compiler rather than at runtime. Party's stack still mounts the detail screen the 1.0.0 way: import PokemonDetailScreen from '@pokedex/detail', straight into component=. The 3.x package has no default export any more, so that import now resolves to the package's namespace object, and the mount stops type-checking:

error TS2322: Type 'typeof import(".../@pokedex/detail/dist/index")' is not
assignable to type 'ScreenComponentType<PartyParamList, "PokemonDetail"> | undefined'.

The detail package has crossed two majors around this app while it wasn't looking, 1.x to 3.x. What 3.x exports is the named PokemonDetailView, a view that demands data as props, so the compile error forces party to write the same four-line container the list app wrote in post 6. A container needs data, and that becomes a wall of its own in The party needs data of its own. Chains like this are what version lag actually costs: not a crash in production, a stack of walls on the day you finally adopt.

The slice itself is the whole point of the post, and it fits on a screen. apps/party/src/partySlice.ts:

import { createSlice, type PayloadAction } from '@reduxjs/toolkit';
import { addToParty, MAX_PARTY, rootReducer, type PartyMember } from '@pokedex/contracts';

export const partySlice = createSlice({
  name: 'party',
  initialState: { members: [] as PartyMember[] },
  reducers: {
    // Private: nobody else dispatches remove, so it ships in no contract.
    remove(state, action: PayloadAction<string>) {
      state.members = state.members.filter(m => m.uid !== action.payload);
    },
  },
  extraReducers: builder => {
    builder.addCase(addToParty, (state, { payload }) => {
      if (state.members.length >= MAX_PARTY) return; // the cap lives with the owner
      state.members.push(payload);
    });
  },
});

export const { remove } = partySlice.actions;

// Importing this module is what adds the reducer to the shared store.
rootReducer.inject(partySlice);

Two things carry the design. The crossing action binds through extraReducers: the party matches the contract's addToParty. Be precise about why that works across separately built apps, because it is easy to credit the wrong thing. builder.addCase reads actionCreator.type and keys its reducer by that string, so what has to agree is party/add, not the identity of the creator object. Two copies of the contract would still match. Defining the string, the cap and the read shape once instead of retyping them per side is the versioned package's work: publishing the contract is what prevents that drift, singleton or not. Where runtime singleton identity earns its place is the objects, rootReducer and baseApi: an injection only lands in the store the host wired if both sides hold the same instance.

And the cap guard lives here, in the owner. The contract publishes the number; only the owner enforces it. A dispatcher that forgets to disable its button still cannot push a seventh member.

The last line is the mechanism. inject takes the slice itself (createSlice defaults its reducerPath to name, so the state mounts at state.party, matching PartySliceShape), and importing the module is what performs the injection. That makes the slice a state module: a federated module whose value is its side effect. The party's bundler config exposes it alongside the stack:

exposes: {
  './PartyStack': './src/PartyStack.tsx',
  './partySlice': './src/partySlice.ts',
},

The party also joins the state trio in its shared map: @reduxjs/toolkit and react-redux with the hand-stated version every exports-map package needs in this config, @pokedex/contracts as a singleton, none of them eager, exactly as the list app declares them. Same rule as post 6: the host provides the copies, remotes consume them.

One dev-loop observation, since RTK guards against a hazard here: on paper, re-running this module hot-swaps a new function identity into an existing reducerPath, and RTK's inject refuses to replace it (a console error in development; the original reducer stays live). In this Re.Pack setup the hazard stays theoretical: an edit to the slice file reloads the app rather than hot-swapping the module, so you get a fresh store instead of a double inject. Worth knowing which of the two your stack does before you trust either.

With state to render, the placeholder tab becomes a screen. The interesting lines of PartyScreen.tsx:

import { useDispatch, useSelector } from 'react-redux';
import { MAX_PARTY, type PartySliceShape } from '@pokedex/contracts';
import { remove } from './partySlice';

const members = useSelector((s: PartySliceShape) => s.party?.members ?? []);

Filled slots render the sprite, the name, and a remove control dispatching remove(member.uid); empty slots keep the dashed placeholder up to six; the header counts {members.length}/{MAX_PARTY}; tapping a member pushes PokemonDetail with { id }, the same DetailParams from post 5, no new fields. Note the owner reading its own state through the tolerant shape. Even here the optional earns its keep: the first render can beat the first action into the store, and injection registers the reducer but leaves state.party undefined until an action next reaches it.

State modules load at boot

The slice injects when its module is imported. So far only one thing imports it: the party screen, which also imports remove. That means the slice exists only after the user opens the Party tab, and the Pokédex is about to dispatch into it long before that. Someone has to load the state module early, and only one participant is alive at boot on every path: the shell. apps/host/App.tsx, in an effect:

// Screens load on demand; state modules load at boot.
useEffect(() => {
  import('partyApp/partySlice')
    .then(() => store.dispatch(partyStateReady()))
    .catch(err => console.warn('party state module failed to load', err));
}, []);

The host already declares partyApp in its remotes map, so this adds no coupling it didn't have. It fires the import and holds no reference to the module's contents: the ambient declaration types the module as empty, because the host imports it for the side effect and has no business naming anything inside. Screens stay lazy, because a screen the user has not opened costs nothing to defer.

Loading at boot is a head start, not a guarantee. The chunk crosses the network, and nothing stops a fast finger reaching an Add button before it lands. A party/add dispatched into a store with no reducer for it vanishes without a trace: no warning, no error, Redux ignoring an unmatched action by design. So the resolve is made visible, and this is where partyStateReady earns its keep. inject() swaps an entry in a reducer map and rebuilds the combined reducer, but it never dispatches, so state.party stays undefined until the next action runs through the new reducer. The marker is that action: the .then dispatches it the moment the module resolves, state.party appears, and every subscriber re-renders with the slice in place.

The write side closes the loop by gating on exactly that: the container in The write arrives as a prop disables Add while s.party is undefined. A tap that cannot happen is a dispatch that cannot be lost.

The effect placement is an observation, not a diagnosis. At module scope this import produced Can't perform a React state update on a component that hasn't mounted yet on some cold starts and not others, and moving it into an effect removed the warning across repeated cold starts. What produces the update is not something this post has pinned down: rootReducer.inject() is not the culprit, because it swaps an entry in a reducer map and rebuilds the combined reducer without ever dispatching or calling replaceReducer, so it notifies nobody by itself. Until the update is traced to its source, treat the placement as a local observation: the effect is the arrangement that made the warning stop, and an effect is where React expects a side effect to live anyway.

Nothing awaits that import, so a party server that is down cannot block boot. That run is worth doing rather than trusting. Stop the party dev server and cold-start the app: the federation runtime reports the failed manifest fetch loudly in development ([ Federation Runtime ]: Failed to get manifest. #RUNTIME-003), and the shell carries on. The Pokédex renders, the counter reads an honest 0/6 through the tolerant shape, the Add button stays disabled because partyStateReady never fired, and the app runs without the slice, which is precisely the state PartySliceShape was designed to describe.

One detail from the observed run: the import settles without rejecting, so the .catch never actually fires for this failure; the runtime contains it and reports it on its own. The catch stays, one line guarding the rejection path so a failed load can never surface as an unhandled rejection.

The write arrives as a prop

The Pokédex side of the crossing starts in the detail view, and the detail view is an installed component library: the one place the write must not live. The ownership essay drew this line: a shared component renders what it is given; a write that crosses a domain boundary is wired by the consumer. So @pokedex/detail 3.1.0 is an additive minor with three optional props:

export interface PokemonDetailViewProps {
  pokemon?: PokemonDetail;
  loading: boolean;
  error: boolean;
  onRetry: () => void;
  onAddToParty?: () => void;
  addDisabled?: boolean;
  addLabel?: string;
}

The view renders a button when a consumer hands it onAddToParty and renders nothing when it does not. It still imports no store, no contract, no action creator. The write crosses a domain boundary, so it arrives as a callback and leaves as a tap.

The list app's container wires all three:

function PokemonDetailRoute({ route }: { route: { params: DetailParams } }) {
  const { data, isLoading, isError, refetch } = useGetPokemonDetailQuery(route.params.id);
  const dispatch = useDispatch();
  const members = useSelector((s: PartySliceShape) => s.party?.members);
  const partyReady = members !== undefined;
  const count = members?.length ?? 0;
  const full = count >= MAX_PARTY;
  return (
    <PokemonDetailView
      pokemon={data}
      loading={isLoading}
      error={isError}
      onRetry={refetch}
      onAddToParty={() =>
        data && dispatch(addToParty({ id: data.id, name: data.name, spriteUri: data.spriteUri }))
      }
      addDisabled={full || !partyReady}
      addLabel={full ? 'Party is full' : 'Add to party'}
    />
  );
}

Read what that tap does. A screen owned by the Pokédex team dispatches an action the contract owns, and that action lands in a reducer owned by the party team. Three parties, none importing another's code. The disabled state reads the same MAX_PARTY the reducer guards with, so the button and the cap can't drift. It also holds the button down until state.party exists, so the one dispatch that could be lost is the one that can never be made. And the Pokédex header gets its counter through the identical read:

const partyCount = useSelector((s: PartySliceShape) => s.party?.members.length ?? 0);
// ...
<Text style={styles.partyCount}>My Party {partyCount}/{MAX_PARTY}</Text>

The list app edits no version pin for any of this: it was on ^3.0.0 for both packages, and npm update @pokedex/contracts @pokedex/detail walks both carets to the new minors. Only the lagging app touched its package.json. That is the caret working as intended: a minor arrives on request; a major takes a deliberate edit.

The party's container is the other consumer of the same view, and it wires none of the three props. A Pokémon opened from inside the party shows no Add button at all:

One view, two consumers, one of them wiring a write. That single screenshot is the ownership essay's component rule, running.

The party needs data of its own

That party-side container is the wall promised earlier. Tapping a party member pushes PokemonDetail inside the party's stack, and the container behind it needs getPokemonDetail, which lives in the list app, which the party cannot import. Apps depend on contracts, never on each other, and this is the first time the rule costs something visible.

The tempting exit is a shared data package: @pokedex/data, owning the endpoint both apps need. It would delete the duplication, and for two features owned by one team it might even be right. The price is the one the ownership essay priced: a shared package puts the party's data access on another team's release train. Compatible releases don't force anyone to move, but the day the party needs a fix in that package, or a breaking version lands, the party's ship date waits on another team's review and release. Twenty lines of query definition do not buy that coupling. The party writes its own apps/party/src/detailApi.ts with the same endpoint name, the same queryFn and the same parsePokemonDetail from the contract, copied deliberately:

const detailApi = baseApi.injectEndpoints({
  endpoints: build => ({
    getPokemonDetail: build.query<PokemonDetail, number>({
      // byte for byte, the list app's definition
    }),
  }),
});

export const { useGetPokemonDetailQuery } = detailApi;

Two apps now inject an endpoint named getPokemonDetail into one baseApi, and RTK notices. Run the app, open the Party tab, and the development console prints:

called `injectEndpoints` to override already-existing endpointName getPokemonDetail without specifying `overrideExisting: true`

Left alone, RTK skips the second injection and keeps the first: loudly in development, silently in production, where that guard compiles out. This build declares the duplicate instead: both apps pass overrideExisting: true, the console error goes away, and the last injection wins. Either way load order decides, and neither app controls load order. That is the honest reason the two definitions have to stay identical rather than merely similar.

The cache does not change: one endpoint name means one set of entries, so opening Bulbasaur from the Pokédex and then from the party costs one fetch total. The trap is drift: declared or not, whichever copy load order favours silently wins for both, and once overrideExisting has silenced the console there is no warning left to ignore. The rule, then: keep the copies byte for byte identical, declare the collision so it is visibly deliberate, or name your endpoint something of your own.

Now break it

The claim to attack: the gate on state.party is what stands between a slow chunk and a lost tap. First remove the gate (change the container's addDisabled back to plain full), then comment out the boot import:

// useEffect(() => {
//   import('partyApp/partySlice')
//     .then(() => store.dispatch(partyStateReady()))
//     .catch(err => console.warn('party state module failed to load', err));
// }, []);

Relaunch fresh, and do not open the Party tab. That matters: PartyScreen imports remove from the slice file, so visiting the tab injects the slice as a side effect and hides the bug. A user who goes straight to the Pokédex is how you reproduce it.

Tap Bulbasaur. Tap Add to party. The tap lands, the counter reads 0/6, and nothing else happens. No warning, no error, no console line. Post 6's break-it at least hung a spinner you could stare at. Here the dispatch reached the store, the store found no reducer registered for party/add, and Redux did what Redux does with an unmatched action: nothing, by design. The user's tap reached a store with nothing registered to answer it, and Redux is behaving exactly as documented.

Now say the sharper thing out loud. With the boot import gone, the slice still exists eventually: one visit to the Party tab injects it, and every add after that works. So the failure has a narrower and nastier shape: every add made before the user happens to open the owner's tab is lost in silence, which reproduces for some users and never for others, depending on tab order. And the boot import alone only shrinks the window, from "until the user opens the Party tab" down to "until the chunk lands". It cannot close it, because the network owes you nothing.

Closing it is the gate's job: put the gate back, leave the import commented out, and the same cold start shows an Add button that is simply disabled. Ugly, visible, and honest: a tap that cannot happen instead of a tap that lies.

Restore the import, relaunch, and the button wakes the moment partyStateReady fires; the same tap ticks the counter to 1/6. The pattern is all three pieces: the boot import for the head start, the marker to surface the slice, and the gate for the window neither can close.

Land exactly on this post's finished state. The walkthrough prints the load-bearing files; manifests, configs, tests and the smaller edits live in the tag. To finish with a tree byte-equal to the tag, sweep the reference copy over yours. A file you typed correctly is overwritten with itself, and the sweep fills in what the prose did not print:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-08-client-state /tmp/pokedex-ref-08
cp -R /tmp/pokedex-ref-08/. .

The sweep is also how the behaviour gets its proof: it carries the two regression tests this post's design earned (the party store walked through the vanish-inject-marker-add window, and the list container's Add gate held down until readiness), the mocks and Jest wiring they run on, and the ambient federation declarations the walkthrough summarised rather than printed.

Run it

Packages published and installed, so the run is three dev servers and a simulator build:

cd apps/list && npm run start:remote      # :8082
cd apps/party && npm run start:remote     # :8083
cd apps/host && npm start                 # :8081
cd apps/host && npm run ios

Cold start lands on the Pokédex with the counter reading 0/6. Do not read that as proof the boot import worked: the tolerant selector returns 0/6 whether the slice is registered or still missing, which is the whole point of it. The proof is the Add button being enabled at all, since it only wakes once partyStateReady has surfaced the slice. Add from a detail, watch the counter tick, and find the member sitting in the Party tab:

🎞️ Animated demo: watch it on warrendeleon.com

Keep adding to six and the cap arrives from both sides at once: the sixth add flips the open detail's button to a disabled state live, because the same selector that counts for the header counts for addDisabled:

Remove a member in the Party tab and the freed slot goes dashed again, the counter drops everywhere at once, and the next add works. One slice, one owner, three surfaces agreeing because they all read the same state through the same shape.

What you built, and what's next

The app now owns something. The party lives in a slice the party app alone owns, registered at boot into a store the host wired around the contract's rootReducer. Registered, not populated: state.party stays absent until the next action reaches the combined reducer. The partyStateReady marker is that action, and the tolerant read shape covers every moment before it fires. The one interaction that crosses (addToParty, its cap, its read shape) ships versioned in the contract, the write reaches the shared detail view as a prop its consumer wires, and the party fetches its own data rather than borrow another team's release schedule. You have also watched the failure this design exists to prevent: a dispatch into a slice whose owner never loaded, dropped without a sound.

One honest limitation stands: restart the app and the party is gone. The slice lives in memory, persistence is a different post's problem, and pretending otherwise would be the kind of quiet scope creep this series tries to avoid.

The sharper question is the one this stack keeps raising. The party is six items and one rule, and it took a store, a contract minor, an injected reducer and a boot import to cross the seam politely. RTK made that crossing possible; it did not make it small. Next, the series rebuilds this exact app on TanStack Query and Zustand, the stack most React Native teams reach for first, and watches what federation does to that choice.

Sources

Redux Toolkit: combineSlices — the injectable root reducer and inject
Redux Toolkit: createAction — prepare callbacks, and nanoid shipping with RTK
RTK Query: code splitting — injectEndpoints and the overrideExisting guard
PokéAPI — the free REST API the app fetches from
react-native-module-federation — the companion repo, at the tag post-08-client-state

Who owns what: boundaries, teams and coupling in a federated React Native app

Warren de Leon — Mon, 10 Aug 2026 00:09:24 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

A plain React Native app usually avoids this argument, because the common shape is one team, one repo, one store. Nothing about React Native requires that; a monorepo with several teams and workspace packages has the same ownership questions without any federation involved. A screen is a folder, a shared component is an import, and the question of who owns a data definition has an answer too obvious to say out loud: the team does, because there is only one.

Posts 4 to 6 of this series took that arrangement apart on purpose: two tab features that build and ship on their own, a screen that travels between them as a versioned package, one store filled at runtime by code the shell has never seen. Every step forced an ownership call: where the shared screen lives, who may touch the store, where a data definition sits. Each call got a paragraph at the moment the tutorial made it. This post gathers those calls and argues them once, as a whole.

It is written as a set of tests, not a set of verdicts. Each section states the reasoning and the conditions under which it holds; change the conditions (team count, trust between teams, release cadence, the size of the platform team) and some of the answers flip honestly. Take the tests away, hold them against your own org chart, and disagree with this series precisely.

The first test: do you need any of this?

Every problem in this essay is bought, not inherited. A single-team app organised feature-first already draws the boundaries that matter: a folder per domain, with the domain's screens, hooks and API calls inside it, and every crossing visible in review as an import. That model costs nothing to run: no registry, no version numbers, no second dev server. A boundary can be redrawn in an afternoon with a file move, and an emergency can cross one with an import and a TODO.

Federation is what happens when the folders become teams. The folder model's weakness is the release train, not the boundaries: every folder still ships in one binary, on one date, gated by the slowest feature on it. When separate teams need separate release dates, the folder boundary has to become a deployment boundary, and every question in this essay follows from that promotion.

So the first test is the cheapest one, and it gates the rest.

The gate. Does more than one team ship this app? If not, stop at folders. Every test in this essay assumes the answer is yes.

The first post of this series weighs the trade in full and lands where this paragraph does: federation converts organisational friction into technical machinery, and an app without the friction pays for machinery it never uses.

A boundary is a team, not a screen

When the Pokémon detail screen needed a home both tabs could reach, the federated answer suggested itself: a third remote, on its own port, declared in both consumers' maps. Post 5 gave that option a fair hearing: it works mechanically, Module Federation resolves nested remotes without complaint, and the screen stays updatable without touching either consumer. The answer was still no, in the sentence this whole essay grows from: a federation boundary is a deployable, and teams cut deployables along domains.

The refusal is about running costs. A remote carries costs a folder never does: a dev server to run, a pipeline to keep green, a version to publish, and a failure mode of its own when its bundle fails to arrive over the network. Those costs are fixed per boundary, and a team absorbs them as overhead on a domain it was going to own anyway. A screen has no team behind it. Cut a screen loose as its own deployable and the overhead turns up while the owner never does; grant that status once and there is no principled place to refuse the next screen. The end of that road is an app per screen, and a release process that is all coordination and no shipping.

📊 Diagram: view it on warrendeleon.com

So the screen shipped as @pokedex/detail instead: a package on a registry, installed by both tabs, mounted by each inside its own stack. The tabs stay the deployables; the screen is a dependency. This is Conway's law used deliberately: if the system is going to mirror the communication structure anyway, draw the module lines where the team lines already are.

Test 1Does this boundary have a team behind it?

The test cuts in both directions: it refuses remotes to screens, and it grants them to domains that have outgrown their folder.

A shared component renders what it is given

Web micro-frontends have a respectable pattern in which a shared fragment arrives smart: it fetches its own data, owns its own loading states, and drops into any host as a finished feature. The appeal is real. One team keeps pixels and data behind one seam, consumers write a single line, and a data fix rolls out with no consumer changing code. Plenty of web micro-frontend setups run this way coherently, at web deployment cadence.

The price is in what the fragment has to carry. A component that fetches carries an opinion about every layer beneath it: an HTTP client, a cache, a retry policy, an auth story. Every consumer inherits those opinions without seeing them. Two such fragments on one screen can disagree about all of it. On mobile the inheritance weighs more, because whatever the fragment carries is duplicated into a bundle a phone has to download.

Post 6 drew the line the other way. PokemonDetailView takes a Pokémon, a loading flag, an error flag and a retry callback, and renders them. That is the whole surface, and the whole arrangement fits in the consumer's container:

const { data, isLoading, isError, refetch } = useGetPokemonDetailQuery(route.params.id);
return <PokemonDetailView pokemon={data} loading={isLoading} error={isError} onRetry={refetch} />;

Going live added no dependencies to the package at all: the same four peers as the static version (the contract, React, React Native, the safe-area context) and Redux nowhere among them, because where the data comes from is the app's business and what it looks like is the library's.

Test 2Does this component know where its data comes from?

A yes is worth stopping on. It can be the right call, for a widget a platform team owns end to end and every consumer wants identical. It is misdrawn when the fetching is incidental to what the component is for, because then what is being shared is a piece of one team's app wearing a component's name.

The practical check takes a minute: render it in a bare app with hardcoded props. Every provider, client or store it demands before it renders is a piece of one app's runtime the package now asks every consumer to rebuild. A theme context is a reasonable ask; a query client wired to one team's endpoints is an app wearing a component's name.

Data definitions live with their domain

That last release split the screen in two, the view in a package and the fetch in an app, and the split had to put the endpoint definition somewhere. The somewhere is the rule. getPokemonDetail landed in the list app, next to getPokemonList, because Pokémon data belongs to the Pokédex domain and the list app is where that domain lives. The view is fed the result as props and never learns the endpoint exists.

The counter-instinct says data code is infrastructure and belongs with the rest of the infrastructure, down in the shared layer. The series splits that claim in two. baseApi, the HTTP layer with its cache and tag machinery, genuinely is infrastructure: it carries no domain knowledge, and every team already depends on it the way they depend on React, so it lives in the contract package and everyone couples to it. A feature endpoint is different. It encodes what one domain fetches, when, and what it exposes, and whoever owns that definition ends up owning the questions, the bugs and the migrations that come with it. Move a domain's endpoints into a shared layer and the layer's owners slowly become the owners of every domain's data plumbing, without the domain knowledge that would make the job possible.

Test 3Does this definition live with its domain?

An endpoint (what a domain fetches and when) travels with the domain. Machinery with no domain knowledge is shared. Models and parsers sit in between, and the split follows the backend: the schema for a wire format every consumer already depends on lives in the contract package (Test 4's logic), while a schema only one domain reads stays with that domain, which is why this series parses PokéAPI's REST payloads in the contract and post 10 keeps its GraphQL parse inside the list app.

Duplication is cheaper than a dependency between teams

In the next post the party remote starts holding state of its own, and its first need is Pokémon data for a tapped slot: data the Pokédex domain already knows how to fetch. The tidy instinct proposes a shared data package: one definition, two consumers, no drift. The series does the untidy thing instead and has the party team write its own endpoint file. It comes to about twenty lines and looks like a failure of housekeeping. The file it duplicates, the Pokédex's own, trimmed to its shape:

const detailApi = baseApi.injectEndpoints({
  endpoints: build => ({
    getPokemonDetail: build.query<PokemonDetail, number>({
      async queryFn(id, _api, _extra, baseQuery) {
        const res = await baseQuery(`pokemon/${id}`);
        return res.error ? { error: res.error } : { data: parsePokemonDetail(res.data) };
      },
    }),
  }),
});

Count what the tidy version costs. A data package shared between two feature teams is a dependency between peers. A compatible release lands quietly, because consumers sit on a caret and adopt when they next install. But the changes worth making to a shared definition are not all compatible, and the day one lands breaking, every consumer has to be moved before the old version can go. Releases chain: bump the package, wait for the other team to take the bump, then ship the thing you actually wanted to ship. And the package itself needs an owner: one of the two teams answers for its bugs, or nobody does. A shared definition between peers does not remove the coordination; it converts drift you can see into scheduling you have to do.

Post 5's loose peer range let one team's app pair an old contract with a new screen, every compiler stayed green, and a user got a sentence with a hole in it:

Twenty duplicated lines cost twenty lines. Each copy follows its own team's needs and ships on its own team's dates, and the drift between them stays visible, because both parse the same wire format from the same backend: the copies can diverge in what they keep and how they shape it, but a divergence shows up against the shared payload rather than hiding behind two different ones. When the duplication grows past a file (five endpoints, ten), the answer changes, and The coupling test says how to tell.

The coupling test

The duplication rule needs a limit, because teams couple to shared code all the time and are right to: React, the navigation runtime, baseApi, the contract types. The line between those and the peer data package is the most reusable test in this essay.

Test 4Does this dependency already exist, or does sharing invent it?

Couple to what you already depend on; refuse the dependency that sharing itself creates.

A client generated from the backend's API specification is fine to share, because it couples its consumers to the backend, a dependency every one of them already has. When the specification changes incompatibly, every consumer was affected the moment it changed, and the generated client surfaces the fact at build time instead of in production; an additive change waits politely for each consumer to care. The contract package passes the same test: params and module shapes are agreements the apps were already bound by implicitly, written down where every compiler can see them. The peer data package fails it. Nothing about the party domain depended on the Pokédex team's release schedule before the shared package existed; the package is what would create that dependency.

📊 Diagram: view it on warrendeleon.com

The pull of the shell

Every rule so far pushes code outward, into domains and packages. One argument pushes the other way, and it deserves the longest hearing in the essay, because it is usually made by the most careful engineer in the room.

Endpoints multiply. Several teams fetch overlapping data. Someone proposes the obvious consolidation: move the shared capability up into the shell, where the platform team can hold one definition of everything. One HTTP layer, one auth story, one set of data definitions, consistent behaviour by construction, drift impossible. Nobody proposes this cynically. On pure technical grounds it delivers exactly what it promises, and one definition really is easier to reason about than four copies.

The costs arrive from two directions. The first is organisational, and it lands before any code is written: escalating a capability to the shell makes the platform team a precondition. A feature team that needs a shell-level change cannot start until another team schedules the work, builds it and ships it. Its start date now sits inside someone else's sprint. Multiply that by every team with a request, and the platform team becomes a queue in front of the whole programme, while inheriting, request by request, domain knowledge it never owned and cannot keep current. The word to sit with is start: the feature team is stopped, and it stays stopped until a team with different priorities ships.

Test 5Can the feature team start without another team shipping first?

Escalating a capability to the shell fails this one by design.

The second cost is specific to mobile: the shell is the binary, so shell code ships at App Store cadence. Build, submit, review, staged rollout, then a long tail of users who never update at all.

A capability moved into the shell moves onto the App Store train, and a schema tweak that rides a store review is the exact cost this series adopted federation to escape. Escalation reintroduces it quietly, one capability at a time.

The platform layer genuinely earns one kind of code, whether it rides in the shell binary or in a platform-owned package like the contract: the slow-moving kind. The HTTP client, auth, baseApi's machinery, observability, the runtimes every remote resolves against. The pattern across that list: capability that changes slowly, carries no domain knowledge, and was already depended on by everyone. The list grows rarely, and each addition needs an argument, because everything on it inherits the binary's cadence.

Inner source: the workable middle

Between "every team waits on the platform team" and "no shared capability at all" there is a middle that large orgs have a name for: inner source. Run the shared code like an open-source project that happens to be internal: the shell, the contract package, a component library, a shared data layer if your org decides it wants one. The platform team are the maintainers and code owners. Product teams send pull requests.

The blocking mechanism changes shape rather than disappearing. A feature team that needs a shell-level change writes the change itself, against the shared repo's contribution rules, and waits for a review instead of a roadmap slot. The platform team's job shifts from build-everything to review-and-steward: it holds the bar on quality and coherence and stops being the queue. The Pokédex team adding a component to the shared library becomes a pull request, not a ticket in another team's backlog. So does the party team's schema addition, if a shared data layer is the choice your org made after all.

The costs are real. Review latency does not vanish; a contested pull request can wait as long as a roadmap slot ever did. The platform team ends up maintaining code it did not write, a genuine burden the day the contributing team moves on. And the model only works on real contribution infrastructure:

Before the first PRWhat inner source runs on

Contribution conventions a stranger can follow, written down
CI a contributing team can run without asking anyone
Ownership files that route each review to the right people

Inner source pays for itself when contributions come often enough to justify that overhead.

“Just open a PR” against an undocumented repo is a politeness, not a process. Without the contribution infrastructure, inner source is the queue with a friendlier name.

The tests, and what moves the answers

The whole argument fits on one map, each box holding what it owns and the cadence it ships at:

📊 Diagram: view it on warrendeleon.com

Five tests, in the order the series met them:

The five testsWho owns what

1Does this boundary have a team behind it? Domains get remotes; screens get packages.
2Does this component know where its data comes from? A shared component renders what it is given; data arrives as props.
3Does this definition live with its domain? Machinery is shared; endpoints travel with the domain that owns the data. Parsers and schemas are the judgement call, and this build splits them by who reads them: the REST schemas every app depends on sit in the contract, while the GraphQL schema only the list reads stays in the list app.
4Does this dependency already exist, or does sharing invent it? Couple to the backend you already depend on; refuse the peer package that manufactures a schedule dependency between teams.
5Can the feature team start without another team shipping first? If not, the capability sits at the wrong level, or the process around it does.

All five sit behind the gate: more than one team ships this app. If not, folders answer every one of them for free.

None of these produce one answer for every org; they tell you what each option costs in yours. Two teams that trust each other and release together can share a data package and barely feel the coupling. An app with three teams and a quarterly cadence might keep everything in the shell and never notice the price. If your org cut these lines differently and the seams hold, that is a different answer to the same tests, and worth defending on its own terms.

The next post puts the tests straight to work. The party grid has been empty since post 4, because nothing in the app can reach it. The party team is about to fill it with state it owns, and the first decisions on the way are exactly the ones this essay just argued: who owns the slice, where the endpoint file goes, what the contract carries. The rules stop being prose and start being files.

Sources

Micro Frontends — Cam Jackson's survey, including the self-contained fragment pattern this essay argues against for mobile
Conway's law — the 1968 paper: systems mirror the communication structures of the organisations that build them
InnerSource Commons — the practice, its patterns, and the contribution infrastructure it depends on
Team Topologies — Skelton and Pais on platform teams and stream-aligned teams, the vocabulary behind the shell debate
react-native-module-federation — the companion repo whose decisions this essay defends

One shared store: server state across federated remotes in React Native

Warren de Leon — Mon, 03 Aug 2026 00:07:47 +0000

📚 React Native Module Federation series — read it in full on warrendeleon.com, where new parts land first.

The last post ended with a sentence with a hole in it: a screen rendering "Opened from the " and then nothing, because a type checked at build time is no help against a value that only shows up at runtime. It closed on a promise, too: real data, one store, shared across the remotes. This post keeps the promise, and the hole gets its proper answer along the way.

It leans on server state and client state from the short break in the series. The split between data a server owns and data the app owns is assumed here, not re-explained. This post is about one half of it, server state, under federation: one Redux Toolkit (RTK) store in the host, one RTK Query cache, and the Pokédex domain filling it with both its endpoints, while the installed @pokedex/detail view renders what it is fed. Live PokéAPI data replaces every hardcoded Pokémon in the app, both drifted copies included.

The shape we're building, before any code:

📊 Diagram: view it on warrendeleon.com

The one thing to hold in your head: baseApi is a single object, and every side imports the exact same one. That is what makes the cache shared. Break that, and the app breaks in a way worth seeing, so we will break it on purpose near the end.

Carry on from your own post 5 code if you built along. Otherwise, start from its finished state:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-05-contracts

The contract package grows a runtime seam

So far @pokedex/contracts has held only types. Every export was erased at build, so nothing from it reached a bundle. Now it gains its first runtime export: the RTK Query API object the whole app fetches through.

The host looks like the natural home for it. The host owns the store, the store owns the cache, and an API object next to the store it feeds is where a single app would put it. In a single app that instinct is right. Under federation it fails on identity: a consumer can only add endpoints to the same baseApi instance the host store wired in, and an instance that lives inside the host's source is one nothing else can import. The contract package is the one module every side already resolves to a single copy of, because it is a Module Federation singleton. Put the instance there and a consumer's baseApi.injectEndpoints({...}) registers against the one cache and middleware the store already runs. One instance means one HTTP cache, one deduplication pipeline, one tag graph across every feature, including features shipped long after the shell. packages/contracts/src/api.ts:

import { createApi, fetchBaseQuery } from '@reduxjs/toolkit/query/react';
import { z } from 'zod';

export const baseApi = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: 'https://pokeapi.co/api/v2/' }),
  tagTypes: ['PokemonList'],
  endpoints: () => ({}),
});

export interface PokemonSummary {
  id: number;
  name: string;
  spriteUri: string;
}

export interface PokemonDetail {
  id: number;
  name: string;
  spriteUri: string;
  types: string[];
}

const PokemonListResponseSchema = z.object({
  // The url is not just any string: the row's id is derived from it, so the schema
  // polices the trailing numeric id a PokéAPI resource url carries.
  results: z.array(z.object({ name: z.string().min(1), url: z.string().regex(/\/\d+\/?$/) })),
});

const PokemonDetailResponseSchema = z.object({
  id: z.number(),
  name: z.string(),
  types: z.array(z.object({ type: z.object({ name: z.string() }) })),
});

export function artworkUri(id: number): string {
  return `https://raw.githubusercontent.com/PokeAPI/sprites/master/sprites/pokemon/other/official-artwork/${id}.png`;
}

export function idFromResourceUrl(url: string): number {
  const match = url.match(/\/(\d+)\/?$/);
  if (!match) {
    throw new Error(`PokéAPI resource URL has no trailing id: ${url}`);
  }
  const id = Number(match[1]);
  if (!Number.isSafeInteger(id) || id < 1) {
    throw new Error(`PokéAPI resource URL id is out of range: ${url}`);
  }
  return id;
}

function formatName(name: string): string {
  return name
    .split('-')
    .map(word => word.charAt(0).toUpperCase() + word.slice(1))
    .join(' ');
}

export function parsePokemonList(raw: unknown): PokemonSummary[] {
  const { results } = PokemonListResponseSchema.parse(raw);
  return results.map(entry => {
    const id = idFromResourceUrl(entry.url);
    return { id, name: formatName(entry.name), spriteUri: artworkUri(id) };
  });
}

export function parsePokemonDetail(raw: unknown): PokemonDetail {
  const parsed = PokemonDetailResponseSchema.parse(raw);
  return {
    id: parsed.id,
    name: formatName(parsed.name),
    spriteUri: artworkUri(parsed.id),
    types: parsed.types.map(entry => formatName(entry.type.name)),
  };
}

createApi with no endpoints builds an empty shell: a reducer, some middleware, and an injectEndpoints method the consumers will call. fetchBaseQuery is a small wrapper over fetch that prepends the base URL and parses JSON. tagTypes names the one label this app invalidates by; it does nothing yet, and does real work in the last section.

The two parse functions are the part post 5's broken sentence pointed at. A type is a compile-time promise, and it is gone by the time a response actually lands. A renamed field or a null where a string used to be slips straight through a hand-written cast and crashes three screens later. So each raw response is validated with a Zod schema right at the seam, and a bad shape becomes a value the screen can handle instead of a crash.

The seam has to police everything it depends on, which is why the list schema checks the url's trailing id rather than just z.string(): the id is derived from that url, and a lenient check here would let a malformed payload through as a phantom Pokémon #0. idFromResourceUrl throws for the same reason: a helper that quietly invents an id on bad input is a parser that passes malformed data instead of failing it. The range check earns its two lines too, since a trailing digit run is not yet an id. /pokemon/0/ names nothing, and a digit string long enough to leave the safe-integer range has stopped being the number printed in the url.

The detail schema keeps only what the detail screen renders; the full PokéAPI payload for one Pokémon is close to 300 KB of JSON, and parsing fields nothing displays would just be a bigger surface to break on. Runtime validation gets a post of its own later in the series.

A runtime export and two new peer dependencies are a breaking change, so the version takes a major bump. The number itself needs a glance at your own registry first: post 5's ladder already published 1.1.0 and 2.0.0, and a published number is spent for good, because the registry refuses to reuse it and every install relies on that refusal. So the runtime seam ships as 3.0.3. The major is the story; the trailing patch is parser hardening that landed after first publication. packages/contracts/package.json:

{
  "name": "@pokedex/contracts",
  "version": "3.0.3",
  "dependencies": {
    "zod": "^3.25.76"
  },
  "peerDependencies": {
    "@reduxjs/toolkit": ">=2.10.0",
    "react": "*",
    "react-redux": ">=9"
  }
}

zod is a real runtime dependency, so it ships inside the package. @reduxjs/toolkit and react-redux are peers: the apps install them, and the contract uses their copies rather than bundling its own. Install the package's dev dependencies and publish:

cd packages/contracts
npm install
npm publish

+ @pokedex/contracts@3.0.3

The caret does here what post 5 showed it doing. Every consumer sits on ^1.0.0, so npm install leaves all three apps exactly where they are even with 3.0.3 on the registry. Picking up the new contract is a deliberate move, one app at a time, and one of the three stays put on purpose.

One store in the host

The host gains a store. apps/host/src/store.ts:

import { combineSlices, configureStore } from '@reduxjs/toolkit';
import { baseApi } from '@pokedex/contracts';

export const store = configureStore({
  reducer: combineSlices(baseApi),
  middleware: getDefaultMiddleware => getDefaultMiddleware().concat(baseApi.middleware),
});

export type RootState = ReturnType<typeof store.getState>;
export type AppDispatch = typeof store.dispatch;

The split of ownership is the point of the file. The store lives in the host: one store per app is the shell's job, like the tab bar. The API instance the store is built around lives in the contract package, for the identity reason above. The host owns the wiring; the seam owns the instance.

baseApi.middleware is load-bearing. It runs the cache lifecycle: fetching, deduplication, tag invalidation, cache eviction. Leave it off the store and the first screen to run a query hook throws a full-screen red box in development, with RTK naming the mistake outright:

Warning: Middleware for RTK-Query API at reducerPath "api" has not been added to the store.
You must add the middleware for RTK-Query to function correctly!

Worth pausing on the component stack in that capture: the crash site is PokedexScreen inside __federation_expose_ListStack.chunk.bundle. A remote's screen, in a chunk the host downloaded at runtime, hits an error caused by one missing line in the host's own store file. The failure crosses the module boundary in the opposite direction to everything else in this series. A loud failure, at least. Keep it in mind, because the Now break it sabotage gets no error at all.

The store goes in over the whole tree, so everything federated into it can read the cache. apps/host/App.tsx, the wrapper:

import { Provider } from 'react-redux';
import { store } from './src/store';

export default function App() {
  return (
    <Provider store={store}>
      <SafeAreaProvider>
        <NavigationContainer>
          {/* the tab navigator from post 4 */}
        </NavigationContainer>
      </SafeAreaProvider>
    </Provider>
  );
}

Remotes never create or import a store. They render inside this tree and reach the store through the shared react-redux singleton, the same way they reached the shared safe-area context back in post 3.

Share the state trio

For anything outside the host to inject into the shared baseApi, three packages have to resolve to one copy at runtime: @reduxjs/toolkit, react-redux, and @pokedex/contracts itself. They join the host's shared map as eager singletons, and post 5's hard-won lesson applies to two of them straight away. apps/host/rspack.config.mjs, the additions:

import rtkPkg from '@reduxjs/toolkit/package.json' with { type: 'json' };
import reactReduxPkg from 'react-redux/package.json' with { type: 'json' };

// ...in the shared map:
'@reduxjs/toolkit': {
  singleton: true,
  eager: true,
  version: rtkPkg.version,
  requiredVersion: pkg.dependencies['@reduxjs/toolkit'],
},
'react-redux': {
  singleton: true,
  eager: true,
  version: reactReduxPkg.version,
  requiredVersion: pkg.dependencies['react-redux'],
},
'@pokedex/contracts': {
  singleton: true,
  eager: true,
  requiredVersion: pkg.dependencies['@pokedex/contracts'],
},

A package resolved through an exports map needs its version stated by hand. Both Redux packages do, and @pokedex/contracts does not. Post 5 found this in the same setup: rspack reads the version out of the package it is sharing, and skips the provide for a package resolved through an exports map. It held on these versions, in this configuration, which is the claim being made. @reduxjs/toolkit and react-redux both carry an exports map, so without the explicit version neither would land in the share scope. The contract package has no exports map, so it needs nothing. The bundle-grep from post 5 confirms all three provides register, contract included:

"@pokedex/contracts", version: "3.0.3"
"@reduxjs/toolkit", version: "2.12.0"
"react-redux", version: "9.3.0"

The list remote mirrors the same three entries without eager: the host provides the copies, the remote consumes them. This is the first time @pokedex/contracts appears in any shared map. Until now it was types-only, erased at build, so there was nothing to share. Now it carries baseApi, and one instance is the whole point.

Two of the apps add the packages and bump the contract:

( cd apps/host && npm install @reduxjs/toolkit@2.12.0 react-redux@9.3.0 @pokedex/contracts@3.0.3 )
( cd apps/list && npm install @reduxjs/toolkit@2.12.0 react-redux@9.3.0 @pokedex/contracts@3.0.3 )

The party app is the third, and it gets nothing. No Redux packages, no new shared entries, and both of its installed packages stay where they are: the contract on ^1.0.0 (two majors behind the seam it types against) and the detail screen on ^1.0.0, the static version. That is safe for a precise reason: the party app consumes only types from the contract, and types are erased at build. A runtime major changes what ships in the package's JavaScript; a consumer that never imports any of that JavaScript has nothing to break. Remotes opt into shared state; the shell forces nothing on them.

The list remote: real data

Now the first injection. apps/list/src/listApi.ts, a new file:

import { baseApi, parsePokemonList, type PokemonSummary } from '@pokedex/contracts';

const listApi = baseApi.injectEndpoints({
  endpoints: build => ({
    getPokemonList: build.query<PokemonSummary[], void>({
      async queryFn(_arg, _api, _extra, baseQuery) {
        const res = await baseQuery('pokemon?limit=151');
        if (res.error) {
          return { error: res.error };
        }
        try {
          return { data: parsePokemonList(res.data) };
        } catch (err) {
          return {
            error: {
              status: 'CUSTOM_ERROR',
              error: err instanceof Error ? err.message : 'Invalid PokéAPI response',
            },
          };
        }
      },
      providesTags: ['PokemonList'],
    }),
  }),
});

export const { useGetPokemonListQuery } = listApi;

injectEndpoints adds getPokemonList to the shared baseApi and hands back a typed hook. The endpoint fetches the first 151 Pokémon in one request, hands the raw body to parsePokemonList, and returns either the shaped rows or a caught error. providesTags: ['PokemonList'] stamps the result with the label the host will invalidate by. The shell knew nothing about this endpoint when it was built; the remote adds it to the running store the first time its code loads.

The screen drops its hardcoded five-row array and reads the hook. apps/list/src/PokedexScreen.tsx:

export default function PokedexScreen() {
  const insets = useSafeAreaInsets();
  const navigation = useNavigation<NativeStackNavigationProp<ListParamList>>();
  const { data, isLoading, isError, refetch } = useGetPokemonListQuery();

  if (isLoading) {
    return (
      <View style={styles.centre}>
        <ActivityIndicator size="large" />
      </View>
    );
  }

  if (isError || !data) {
    return (
      <View style={styles.centre}>
        <Text style={styles.error}>Couldn't reach PokéAPI.</Text>
        <Pressable style={styles.retry} onPress={() => refetch()}>
          <Text style={styles.retryText}>Try again</Text>
        </Pressable>
      </View>
    );
  }

  return (
    <FlatList
      data={data}
      keyExtractor={p => String(p.id)}
      contentContainerStyle={{ paddingBottom: insets.bottom + 8 }}
      renderItem={({ item }) => (
        <Pressable
          style={styles.row}
          onPress={() => navigation.navigate('PokemonDetail', { id: item.id })}>
          <Image source={{ uri: item.spriteUri }} style={styles.sprite} />
          <Text style={styles.number}>#{String(item.id).padStart(3, '0')}</Text>
          <Text style={styles.name}>{item.name}</Text>
        </Pressable>
      )}
    />
  );
}

Three states instead of one: a spinner while the request is in flight, an error screen with a retry when PokéAPI is unreachable, and the list. The navigation from post 5 is untouched: tapping a row still pushes PokemonDetail with { id } inside this remote's own stack. What changed is where the rows come from: a cache in the host's store, filled by an endpoint this remote injected, read through a hook that did not exist when the host shipped.

The detail goes live; the library stays a view

Post 5 left a deliberate smell in the detail package: its own private copy of the Pokémon data, drifted from the list's copy, with a comment promising that live data would delete it. This is that moment, and it takes two releases that draw one line.

The line: a component library ships pixels, and data definitions belong to the domain that owns the data. The next post argues that line in full; this one applies it. Pokémon data is the Pokédex domain's, so the second endpoint lands next to the first, in the list app. apps/list/src/detailApi.ts:

import { baseApi, parsePokemonDetail, type PokemonDetail } from '@pokedex/contracts';

const detailApi = baseApi.injectEndpoints({
  endpoints: build => ({
    getPokemonDetail: build.query<PokemonDetail, number>({
      async queryFn(id, _api, _extra, baseQuery) {
        const res = await baseQuery(`pokemon/${id}`);
        if (res.error) {
          return { error: res.error };
        }
        try {
          return { data: parsePokemonDetail(res.data) };
        } catch (err) {
          return {
            error: {
              status: 'CUSTOM_ERROR',
              error: err instanceof Error ? err.message : 'Invalid PokéAPI response',
            },
          };
        }
      },
    }),
  }),
});

export const { useGetPokemonDetailQuery } = detailApi;

A query that takes the id as its argument, fetches one Pokémon, parses it at the seam. No tags: nothing invalidates a single Pokémon yet.

@pokedex/detail goes to 3.0.0: a major, because the props change shape entirely. The static copy and its lookup are gone; what remains is a view: PokemonDetailView takes the Pokémon and the three states as props, renders them, and does nothing else. The list app composes hook and view in a small container on its detail route:

import { PokemonDetailView } from '@pokedex/detail';
import { useGetPokemonDetailQuery } from './detailApi';

function PokemonDetailRoute({ route }: { route: { params: DetailParams } }) {
  const { data, isLoading, isError, refetch } = useGetPokemonDetailQuery(route.params.id);
  return <PokemonDetailView pokemon={data} loading={isLoading} error={isError} onRetry={refetch} />;
}

Where the data comes from is the app's business; what it looks like is the library's. Nothing in the package touches the store, and going live added no dependencies to it at all: the same four peers the static version had, Redux nowhere among them.

Count the cost of going live: one endpoint file in the domain that owns the data, one honest major on the view, and a container of four lines. And the quieter payoff: the list's copy of the data and the package's copy have both gone, so the drift between them has gone too. Both screens now render whatever PokéAPI says, through one cache, and disagreeing with each other is no longer something they know how to do.

Now break it

The claim is that one shared instance holds it all together. The fastest way to trust that is to remove it and watch.

Delete the @pokedex/contracts entry from the shared map in both configs that carry it (host and list), leaving @reduxjs/toolkit and react-redux in place. Restart the dev servers and relaunch.

It spins. Forever. No crash, no red box, and this time nothing in the console either. Twenty seconds in, the only line the dev server has logged is the app starting up. Watch it for as long as you like: nothing else arrives.

The middleware warning from the store section would seem the natural failure here, and the reason it never fires is the whole lesson. With the contract no longer shared, the host bundles its own copy of @pokedex/contracts and the list remote bundles a separate one. Two copies means two baseApi objects. The host store wired the reducer and middleware of its copy, so from where RTK stands the setup is complete and healthy: nothing missing, nothing to warn about. Both of the domain's endpoints registered in the list's copy, one no store ever wired, so the endpoints exist, the hooks run, and the fetches they should trigger go nowhere. Each copy is internally consistent. The mistake sits between them, and nothing at runtime owns "between".

This is the quiet failure the shared-singleton posts keep returning to, and it now has a full ladder. Two Reacts crash on launch. A missing middleware throws a red box that names the file to fix. Two baseApis give you a spinner over a cache that never fills, and the only diagnostic is the absence of everything else. A loud failure is cheap; the silent one costs the afternoon. Put the shared entries back, restart, and the list fills again.

Invalidate across the seam

The tag graph has been sitting unused since the contract declared it. Time to pull it.

Post 4 hid every header with headerShown: false on the tab navigator, and post 5 gave each remote's stack its own headers inside the tab. The host now turns the Pokédex tab's header back on, because it is about to put something host-owned in it. apps/host/App.tsx:

import { useDispatch } from 'react-redux';
import { baseApi } from '@pokedex/contracts';

function RefreshButton() {
  const dispatch = useDispatch();
  return (
    <Pressable
      style={styles.refresh}
      onPress={() => dispatch(baseApi.util.invalidateTags(['PokemonList']))}
      hitSlop={12}
      accessibilityRole="button"
      accessibilityLabel="Refresh Pokédex">
      <Text style={styles.refreshText}>Refresh</Text>
    </Pressable>
  );
}

import { getFocusedRouteNameFromRoute } from '@react-navigation/native';

<Tab.Screen
  name="Pokédex"
  component={PokedexTab}
  options={({ route }) => ({
    headerShown: getFocusedRouteNameFromRoute(route) !== 'PokemonDetail',
    headerRight: () => <RefreshButton />,
  })}
/>

One detail in there deserves a closer look. The detail route brings its own stack header with a back button, and a tab header stacked on top of it would put two bars on screen. So the host hides its bar while the stack sits on the detail, and shows it the moment the stack pops back.

Checking against 'PokemonDetail' looks like the host reaching into the remote's internal route names, and that is exactly what it would be if the name lived in the remote. But it doesn't. It is the route name from DetailParamList in @pokedex/contracts, the same agreement the params come from. Be honest about how much that buys: the host writes the string 'PokemonDetail' by hand, and TypeScript does not connect a bare string to the contract's key. Rename the route in the contract and this comparison keeps compiling while it quietly stops matching. The agreement is real; the compiler is not enforcing this end of it.

RefreshButton needs Pressable and Text added to the react-native import, plus two small style entries; the complete file is in the companion tag.

The host never defined getPokemonList. It holds no reference to the list remote's endpoint, its hook, or its query. All it dispatches is a tag. invalidateTags(['PokemonList']) walks the shared cache, finds every query that provided that tag, and refetches the ones with a subscriber on screen. The list refetches; the detail endpoint, which provides no tags, is untouched. One label, declared in the contract, provided by one feature, dispatched by the host, and the refetch lands in code the dispatcher has never seen.

In a real app the invalidation hangs off a mutation's invalidatesTags rather than a button, but the reach across the module boundary is the same. Teams agree on tag names in the contract the way they agree on types, and that agreement is the entire refresh protocol between them.

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-06-shared-store /tmp/pokedex-ref-06
rm packages/detail/src/PokemonDetailScreen.tsx
cp -R /tmp/pokedex-ref-06/. .

The rm matters: this post deletes that screen, and a copy over the tree adds and overwrites but never removes.

The sweep also brings the Jest transform configuration the store stack needs, the parser regression tests, the per-tab stack changes and the detail refactor this walkthrough described in prose.

Run it

The packages are published and installed, so Verdaccio isn't needed for the run. Three dev servers, one per app, then the simulator build:

cd apps/list && npm run start:remote      # :8082
cd apps/party && npm run start:remote     # :8083
cd apps/host && npm start                 # :8081
cd apps/host && npm run ios

The Pokédex tab shows a spinner for a moment, then fills with the first 151 Pokémon, official artwork included, straight from PokéAPI. Tap a row and the detail route fetches its Pokémon through the same cache. Tap Refresh in the header and the list reloads across the seam:

🎞️ Animated demo: watch it on warrendeleon.com

The party tab still renders its empty grid, contract two majors behind, detail screen still the static 1.0.0, store nowhere in sight, working exactly as it did before this post. Independence includes the freedom to not participate.

What you built, and what's next

The contract package owns the one baseApi every side injects into, so the cache, the deduplication, and the tag graph are shared across features that were built and shipped on their own. The host owns the store built around it. The Pokédex domain fills the cache with both its endpoints, the installed view renders what the containers feed it, the boundary is guarded with a schema, and the host refreshes data it cannot name by dispatching a tag. When the sharing is removed, the failure is a silent spinner; you have seen it once here, so you will know it when it is expensive.

Everything crossing the seam is still server state, though: data a server owns and the cache holds a copy of. Nothing the app itself owns has crossed a module boundary yet, and the app is starting to accumulate things it owns. The party grid is still empty because nothing you do in the Pokédex can reach it. Close the app and reopen it, and nothing you did survives: no party, no favourites, no memory.

Client state is the other half of the split this post started from, and the build-along returns for it in two posts' time. First, the series steps back and argues the ownership calls the last three posts kept making one at a time: where a boundary goes, what a shared component may know, where a data definition lives.

Sources

Redux Toolkit: code splitting — injectEndpoints and adding endpoints to an existing API at runtime
RTK Query — the cache, the tags, and the generated hooks
Zod — the schema library guarding the runtime boundary
PokéAPI — the free REST API the app fetches from
react-native-module-federation — the companion repo, at the tag post-06-shared-store

Tags vs query keys: a small API difference that changes how teams coordinate

Warren de Leon — Mon, 27 Jul 2026 00:12:20 +0000

📚 State Management series — read it in full on warrendeleon.com, where new parts land first.

Tags survive a rename, keys don't

Declarative tags scale to teams. String-based keys don't.

TanStack Query's keys are shorter, lighter, and pleasant to read inside a single codebase. For a feature team that owns every query, the key-based API is the obvious choice. RTK Query's tag system adds ceremony you don't need at that size.

The shape that works for one team becomes a liability across team boundaries. The failure mode shifts from "fix it before merge" to "find it from a support ticket."

One order, two teams

The orders team ships a placeOrder mutation. The catalogue team has a getProduct query that returns an item's details and stock level. When the order succeeds, the cached product is stale (its stock count just changed), and something has to mark it for refetch.

With RTK Query tags

The catalogue team declares what their query holds:

getProduct: builder.query({
  query: (id) => `/products/${id}`,
  providesTags: ['Product'],
}),

The orders team declares what their mutation affects:

placeOrder: builder.mutation({
  query: (order) => ({ url: '/orders', method: 'POST', body: order }),
  invalidatesTags: ['Product'],
}),

When the mutation succeeds, the library walks its cache, finds queries that provide the Product tag, and refetches the ones currently mounted. The orders team never reads the catalogue's code. They don't need to know what query key the catalogue uses or what shape the cache entry takes. They declare intent at a categorical level and the library wires it.

Both teams are coupled to the string 'Product'. That coupling lives in a shared tagTypes list declared in the API module, so it has a single source of truth.

With TanStack Query keys

TanStack invalidates by key, not by category. The orders team writes:

queryClient.invalidateQueries({ queryKey: ['product'] });

For that line to be correct, the orders team has to know the catalogue team's exact query key shape. They go look at the catalogue's code, find the useQuery call, read the key, and copy it into their own invalidation.

The teams are coupled to the same string 'product', but the coupling lives in a different place. It's a magic string in the orders team's mutation handler, with no contract pointing back to the catalogue's query.

What happens when teams drift

Both approaches produce the same outcome when teams stay coordinated. The cached product refetches, the UI updates, the user sees the new stock level. The approaches diverge when coordination slips.

Take a rename. The catalogue team is refactoring. The domain term has shifted. What they used to call "product" is now called "listing" across the API, the docs, and the team's day-to-day language. They rename the query key:

// before
useQuery({ queryKey: ['product', productId], queryFn: fetchProduct });

// after
useQuery({ queryKey: ['listing', listingId], queryFn: fetchListing });

They ship.

In an RTK Query world with tags, the rename has no effect on the orders team's invalidation. Tags are independent of query keys. The catalogue team's query still provides 'Product'. The orders team's mutation still invalidates 'Product'. The wiring holds.

In a TanStack Query world with keys, the rename breaks the orders team silently. invalidateQueries({ queryKey: ['product'] }) now matches zero cached queries. The mutation succeeds. The library doesn't surface an error because finding zero matches isn't one. The user's product page stays stale until they navigate away and back, or until a support ticket surfaces the bug.

No type error. No compile failure. No runtime exception. Stale UI in production.

Where the coupling lives

Both approaches encode the same coupling between the two teams. The difference is where the coupling lives, and what surfaces when it breaks.

Tags couple the teams through a category name: an abstract noun describing a kind of data. It lives in a shared enum. Renames need coordination through that enum, and the rename surfaces at compile time: inside one createApi module, immediately; across independently shipped apps, at each app's next build against the updated shared package.

Keys couple the teams through a string identifier: the literal shape that identifies a cached entry. It lives wherever someone types it. Renames don't need coordination because nothing forces it. They surface when the bug hits production.

Neither behaviour is baked into the words "tag" and "key". A team can hard-code a tag string outside the enum, and a TanStack team can build shared, typed key factories that surface renames just as loudly. The enforcement comes from the shared contract, and the difference is which way each API leans: RTK Query asks for tags from a declared tagTypes list, so the contract is the path of least resistance; TanStack accepts any array, so the contract is something you have to build and police yourself.

That gap in surfacing isn't a flaw in TanStack Query's design. The key-based API is shorter, lighter, and well-suited to a single team that holds every query in its head. The shape stops fitting when the people writing the invalidation and the people writing the query stop being the same people.

Which one fits your team

One team, one codebase. If that's your app, the difference is mostly aesthetic. TanStack's key-based API is shorter and adds no ceremony. The risk of silent invalidation drift is small because you have full visibility into every query key.

Multiple teams shipping independently. Here the failure mode of key-based invalidation starts to compound. Each team's refactor is a possible silent break for any other team that referenced their keys. You can build conventions to soften that (query key factories, shared key constants, code review checklists, integration tests across features), but those are conventions, not enforcement: you're rebuilding what the tag system gives you for free.

A library choice still open, with federation or multi-team work ahead. In that case the tag system is worth understanding before the API shape feels arbitrary. Picking between the two libraries means picking which failure modes you're willing to live with.

The Module Federation series takes up the broader question of state management across independently shipped remotes, in One shared store for the server half and Client state across the seam for the client half. If you're new to the server-vs-client-state split this one assumes, start here.