DEV Community: Warren de Leon

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.

Server state and client state: why React apps need two libraries

Warren de Leon — Mon, 20 Jul 2026 10:32:17 +0000

📚 State Management series — read it in full on warrendeleon.com, where new parts land first.

Almost every React Native app holds two kinds of state that behave nothing alike: server state and client state. Tell them apart and the choice of library mostly answers itself; blur them and you end up building by hand what a library would give you for free.

This post and its follow-up on cache invalidation are a short break from the Module Federation series, because the federated work ahead leans on exactly this distinction. It is easier to get straight in one plain app first.

Two pairings hold up well as an app grows. With Redux Toolkit and RTK Query you keep one store, but server and client state are handled by two different tools inside it: RTK Query is a purpose-built server-state layer, caching machinery and all, and client state stays in plain createSlice slices. With TanStack Query and Zustand you split across two libraries instead, the server cache living in TanStack's own client, outside any store, and client state in a small Zustand store. Either way the two kinds get different handling and are never forced through one. The shortcut that undoes that is one general-purpose store, a thunk per request, and cache logic grown by hand. It is fine on a small app and turns into a second job as it grows.

Two kinds of state

Server state is a local copy of something a server owns: a profile from /users/me, a product list, an order status. The copy is only ever a snapshot, and the original can change the instant after you read it. That one fact is where all the work comes from. A copy of remote data needs caching, so you are not refetching on every mount; deduplication, so two components asking for the same resource fire one request; background refetching, so the screen freshens quietly; retry, for the network that drops; invalidation, so a write can mark related data stale; and garbage collection, to drop what nothing is watching. None of that is peculiar to React. It is what any client owes data it does not own.

Client state is the other half: data the app owns outright. The selected account, a sort order, a form draft, whether a modal is open, the auth tokens you hold after login (where you keep them safely is its own topic), the user's theme and language. It has to be held, it has to be reactive, and once in a while it has to survive a restart. That is nearly the whole list. It cannot go stale, so it needs no caching; there is nothing to refetch, so it needs no background sync. The two are not degrees of the same thing. They have different jobs, and a library built for one is the wrong tool for the other.

What each half asks for

Server state needs a library that already has the machinery. Build it by hand and every feature grows the same scaffolding: a request, a loading flag, an error field, and a branch for each of the three states a fetch can be in. A server-state library hands you all of it behind a hook. On Redux, that library is RTK Query:

export const api = createApi({
  reducerPath: 'api',
  baseQuery: fetchBaseQuery({ baseUrl: '/api' }),
  endpoints: builder => ({
    getProfile: builder.query<Profile, void>({
      query: () => '/users/me',
    }),
  }),
});

export const { useGetProfileQuery } = api;

The component reads one line, and caching, deduplication and the whole loading-and-error lifecycle come with it (retry and refetch-on-focus are opt-ins: the retry wrapper around your base query, and refetchOnFocus plus a setupListeners call):

const { data: profile, isLoading, error } = useGetProfileQuery();

Off Redux, TanStack Query does the same job in the same shape: declare the query, let the library run the cache and the lifecycle.

export const useProfile = () =>
  useQuery({ queryKey: ['profile'], queryFn: getProfile });

Client state needs almost nothing by comparison. A preference has no server to compare against, so whatever the app holds is correct by definition, and caching or refetching would be solving a problem it does not have. A small store is enough. With Zustand:

export const useSettings = create<Settings>()(set => ({
  theme: 'system',
  setTheme: theme => set({ theme }),
}));

No reducer, no dispatch, no lifecycle. On Redux the same thing is a plain createSlice with a couple of setters. Either way it holds a value and lets components react to it. The mistake in both directions is the same: put client state in a server-state tool and you carry machinery it never uses; make one hand-rolled store do both and you rebuild the library's job by hand.

Which split, and when

There is no universal winner between the two pairings, and I would distrust any post that handed you one.

Already on Redux. RTK Query is the shorter road, because it drops the server-state machinery into the store you already run.

A fresh app with no Redux commitment. TanStack Query and Zustand are two focused tools that compose without treading on each other.

A small app. One store with a thunk per request is a perfectly reasonable place to start. Watch for the day you find yourself writing cache logic by hand: that is the signal to reach for a tool that already ships it.

So before you next reach for a slice to hold an API response, stop on the smaller question first: do you need server-state machinery, or just somewhere to keep a value a few components can watch?

Once features stop sharing a codebase the question gets sharper still. When each ships as its own app and loads at runtime, whose cache is authoritative stops being a convenience and becomes something teams have to coordinate. That is where the Module Federation series picks back up. Before then, the next post stays on the server half: how RTK Query's cache tags and TanStack's query keys handle the same invalidation, and why that small API difference decides how well each holds up once more than one team is committing to it.

The contract package: a versioned seam between federated remotes in React Native

Warren de Leon — Mon, 13 Jul 2026 00:05:19 +0000

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

Post 4 ended on a promise: both tabs would want to open the same Pokémon detail screen, and separately built apps would have to agree on what to pass it.

This post builds that, and it takes three changes that need each other. Each remote stops exposing a bare screen and exposes a whole navigation stack, so pushing a detail belongs to the tab that pushed it. The detail screen itself ships as a versioned package both tabs install, not as another deployable, for a reason worth spelling out. And the agreement about what crosses into that screen becomes a package too: a contract with a version number, which is where the real lesson of this post lives. At the close we break the agreement on purpose, three rungs up a version ladder, and end at a hole no compiler in the codebase can see.

Carry on from your own post 4 code if you built along. Otherwise:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-04-host-shell

Each tab grows a stack

In post 4 each remote handed the host a bare screen and the host arranged them into tabs. A detail screen changes what "inside a tab" means: tapping a row should push a new screen while the tab bar stays put, and whoever owns that push owns navigation inside the tab. That is the remote's business, not the shell's. So each remote now exposes a stack.

apps/list/src/ListStack.tsx:

import React from 'react';
import { createNativeStackNavigator } from '@react-navigation/native-stack';
import PokemonDetailScreen from '@pokedex/detail';
import type { ListParamList } from './routes';
import PokedexScreen from './PokedexScreen';

const Stack = createNativeStackNavigator<ListParamList>();

export default function ListStack() {
  return (
    <Stack.Navigator screenOptions={{ headerShown: false }}>
      <Stack.Screen
        name="PokedexList"
        component={PokedexScreen}
        options={{ title: 'Pokédex' }}
      />
      <Stack.Screen
        name="PokemonDetail"
        component={PokemonDetailScreen}
        options={{ headerShown: true, title: '' }}
      />
    </Stack.Navigator>
  );
}

That import PokemonDetailScreen from '@pokedex/detail' is the second change of the post, and we will come back to it. First, the wiring around it. The remote's public surface changed: it exposes ./ListStack where it used to expose ./PokedexScreen, so its rspack config renames the entry in exposes, and the host's two lazy imports become listApp/ListStack and partyApp/PartyStack. The party app mirrors all of it with its own PartyStack.

The share map evolves too, in both directions of post 4's rule. The remotes now import @react-navigation/native, @react-navigation/native-stack and react-native-screens, and all three carry identity: navigation context, module-level registries, a native view registered once per process. So all three join the shared singleton maps on every side. Being imported by more than one party is what put them on the table; carrying identity is what decides the entry. Two of the new entries state version by hand:

'@react-navigation/native': {
  singleton: true,
  version: navPkg.version,
  requiredVersion: pkg.dependencies['@react-navigation/native'],
},

A package resolved through an exports map gets no provide without a stated version. In this setup rspack reads the version out of the package it is sharing, and does not manage it for a package behind such a map, which React Navigation has. Treat that as behaviour verified here, on these versions, rather than a general rule about exports maps. Without the explicit version the bundler silently skips the provide: nothing lands in the share scope, and the app dies at launch on RUNTIME-006 (eager) or quietly bundles a duplicate (not eager). The navigation packages need it; react-native-screens doesn't. Checking for an exports field in a package's package.json tells you which treatment it needs.

Run it and the product change is visible: tap a row, the detail pushes inside the tab, and the tab bar stays on screen.

🎞️ Animated demo: watch it on warrendeleon.com

Where does the shared screen live?

Both stacks mount the same detail screen. In this series' product it is one screen; in a real app it is the sort of thing two teams genuinely share. Where does it go?

The federated answer suggests itself: a third remote, a detailApp on its own port, declared in both consumers' remotes maps. It works mechanically (Module Federation resolves nested remotes without complaint) and it keeps the screen updatable without touching either consumer. It is also the wrong cut. A federation boundary is a deployable, with a dev server, a deploy pipeline, and a failure mode all its own. Teams cut those boundaries along domains: one team, one domain, one remote, several screens inside it. Screen count is the wrong measure. What earns a federation boundary is a team that owns the thing and needs to release it on its own schedule, and one screen rarely comes with either. Here the detail screen belongs to the same domain as the list, so it travels as a package rather than a deployable.

A screen two domains share is a component, and shared components have had a delivery mechanism for decades: a package. So the detail screen ships as @pokedex/detail, published to a registry and installed by both tab apps, each of which mounts it in its own stack wherever it sees fit. The tabs stay the deployables. The screen is a dependency. That rule gets argued in full two posts from here.

packages/detail/src/PokemonDetailScreen.tsx, the parts that matter:

import type { DetailParams } from '@pokedex/contracts';

const POKEMON: Record<number, { name: string; types: string[] }> = {
  1: { name: 'Bulbasaur', types: ['Grass', 'Poison'] },
  4: { name: 'Charmander', types: ['Fire'] },
  7: { name: 'Squirtle', types: ['Water'] },
  25: { name: 'Pikachu', types: ['Electric'] },
  133: { name: 'Eevee', types: ['Normal'] },
};

export interface PokemonDetailScreenProps {
  route: { params: DetailParams };
}

export default function PokemonDetailScreen({ route }: PokemonDetailScreenProps) {
  const { id } = route.params;
  const pokemon = POKEMON[id];
  // renders the dex number, name, sprite and type chips
}

Two things are deliberate here. The screen carries its own copy of the Pokémon data: the list app has one too, and the two have already drifted, because the list needs names and this screen needs types as well. Two copies of the same facts is a smell, and it is planted on purpose: live data deletes both in the next post. And the props are typed structurally ({ route: { params: DetailParams } }) rather than by importing React Navigation's types. The screen is mounted by two stacks it has never seen, so it states the shape it needs and stays free of a navigation dependency. Its DetailParams import is the contract package, which this post now needs to explain.

The agreement no app can own

Look at what has to line up. The list app pushes PokemonDetail with { id }. The party app will push the same route once it has members to tap. The screen reads route.params.id. Three codebases touch one shape, and none of them can define it for the others: a definition in the list app is invisible to the screen's package, and hand-copying the type into each codebase is drift with a delay on it.

The same problem exists one level up, where the host consumes the remotes. The host's ambient declarations describe modules that have no file to point at:

declare module 'listApp/ListStack' {
  import type { ListStackModule } from '@pokedex/contracts';
  const ListStack: ListStackModule;
  export default ListStack;
}

An ambient declaration is a hand-written promise. TypeScript believes it because there is nothing to check it against: the module it describes resolves at runtime, from a server, long after the compiler exits. Pointing the declaration at a type from an installed package does not make the promise checkable; it makes the promise shared, so the host and the remote at least describe the surface from one definition instead of two guesses. What it still cannot catch, honestly: if the remote renames its expose, the declaration goes stale and the compiler stays green. The check on that seam does not exist at build time. Now break it: the version ladder is built on that missing check.

So the agreements live in @pokedex/contracts, a package that holds types and nothing else:

// packages/contracts/src/params.ts
export interface DetailParams {
  id: number;
}

export type DetailParamList = {
  PokemonDetail: DetailParams;
};

Each stack embeds the fragment in its own param list (type ListParamList = DetailParamList & { PokedexList: undefined }), the screen package reads DetailParams, and the host types its module declarations from the same place. Everything in the package is erased at build. Nothing from it reaches a bundle; it exists so that every tsc in the repo checks against one definition.

Publish both to a registry

A package needs a registry, and file: paths won't do: a path is a location on one machine, and the point of both packages is that separately built apps (in a real org, separately owned repos) install the same artefact by name and version. Verdaccio is an npm registry in a single process, good enough to make everything about the flow real:

npx verdaccio                                    # :4873, stays up
npm adduser --registry http://localhost:4873     # any username, password and email

A one-line .npmrc at the repo root points the scope at it (@pokedex:registry=http://localhost:4873/) and both packages publish:

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

+ @pokedex/contracts@1.0.0
+ @pokedex/detail@1.0.0

The detail package declares its needs as peers rather than bundling them:

"peerDependencies": {
  "@pokedex/contracts": ">=1",
  "react": "*",
  "react-native": "*",
  "react-native-safe-area-context": ">=5"
}

A peer range is a claim about compatibility, and >=1 is a loose one: it says this screen works with any contract from 1.0.0 up. Loose ranges buy consumers flexibility to upgrade at their own pace. What they cost is precision, and Now break it: the version ladder shows the price.

The two tab remotes install both packages; the host installs only the contract, because nothing in the shell renders a detail screen. A real install, by version, from the registry, each app named:

( cd apps/host && npm install @pokedex/contracts@1.0.0 )
( cd apps/list && npm install @pokedex/contracts@1.0.0 @pokedex/detail@1.0.0 )
( cd apps/party && npm install @pokedex/contracts@1.0.0 @pokedex/detail@1.0.0 )

Every consumer unpacks its own copy into node_modules, holding the version it asked for. Counting the checkout: the host, the list app and the party app each hold one, and the detail package holds one for its own build, so four copies of the contract sit on disk. That sounds like the drift problem again, until you notice the difference: these copies have version numbers on them, and version numbers are what the rest of this post is about.

Now break it: the version ladder

The setup works. Both tabs mount the installed screen, the pushes type-check against the installed contract, and the simulator behaves. The interesting question is what happens when the packages move and the apps don't, because in a real org they won't, not in step. Three rungs.

1.1.0, an addition

The party will eventually pass a slot-instance id when a tapped Pokémon came from a party slot. Optional field, additive change:

export interface DetailParams {
  id: number;
  uid?: string;
}

Bump to 1.1.0, build, publish. Then, in the list app, the part most explanations skip:

npm install

up to date, audited 1188 packages in 926ms

Nothing happens. The lockfile pins 1.0.0, and npm install honours the lockfile. The caret in package.json says what this app would accept; the lockfile decides what it gets. Taking the minor is a deliberate act:

npm update @pokedex/contracts

changed 1 package, and audited 1188 packages in 868ms

Now npm ls @pokedex/contracts shows the new resolution, including the screen package accepting it through its loose peer:

+-- @pokedex/contracts@1.1.0
`-- @pokedex/detail@1.0.0
  `-- @pokedex/contracts@1.1.0 deduped

tsc passes with no source change anywhere: a consumer built against 1.0.0 never passes uid, and still satisfies the type. That is what makes an additive change safe to roll out unevenly.

2.0.0, a field that has to be there

The next change is the kind that breaks. The detail screen wants to show where it was opened from, so the param becomes required, and the screen learns to render it:

export interface DetailParams {
  id: number;
  uid?: string;
  source: 'pokedex' | 'party';
}

A required field invalidates the old shape, so the contract goes to 2.0.0. The screen package follows it there: @pokedex/detail@2.0.0, built against the new contract, rendering a small origin line from route.params.source. Back in the list app, with both on the registry:

npm install

up to date, audited 1188 packages in 886ms

It stays on 1.1.0. The caret refuses the major without being asked, which is the one piece of this whole arrangement that works by default.

The blind spot

Three teams ship at three speeds. The party team adopts both 2.0.0s and compiles clean: it pushes nothing yet, so the new requirement costs it nothing. The list team has a release out and stays on the 1.1.0 contract. But the screen package is just a dependency, and dependencies get bumped: someone in the list team takes the new screen without taking the new contract.

npm install @pokedex/detail@2.0.0

changed 1 package, and audited 1188 packages in 1s

No warning. The screen's peer range says >=1, the list app holds 1.1.0, and 1.1.0 >= 1. npm is satisfied:

+-- @pokedex/contracts@1.1.0
`-- @pokedex/detail@2.0.0
  `-- @pokedex/contracts@1.1.0 deduped

Here is the part worth slowing down for. The list app now bundles a screen whose runtime code reads route.params.source. Ask what its compiler checked, and the answer is: the screen's published type declarations say the props take DetailParams, imported from @pokedex/contracts and resolved to whatever copy the consumer installed. The list app resolved it to 1.1.0, where source does not exist. So the list app's push of { id } type-checks perfectly against the very screen that is about to read a field it never sent. Every tsc in the codebase is green, and every one of them is checking a different sentence than the one the runtime will speak.

At runtime, the list tab pushes Bulbasaur:

"Opened from the ", and then nothing. No crash, no red box, no warning in any terminal. A sentence with a hole in it, shipped to a user.

The contract did not fail. It did what a compile-time contract can do, which is hold each app to the version that app installed. The loose peer did not fail either; it did exactly what >=1 says. The hole is between them: a type is a compile-time promise, and it is gone by the time a value actually crosses. Checking the value that arrives is a different job, done by different tools, at a different time.

What you built, and what's next

Navigation moved down into the remotes. The shared screen ships as a versioned package, because a federation boundary is a team's domain and a screen is a component. The agreements (params and module shapes) live in a contract package every side installs, and semver governs how the three codebases drift: minors roll out unevenly and harmlessly, majors wait for consent, and the one failure that slipped through did it silently, in the gap between a loose peer range and an erased type.

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. Most files you typed are overwritten with themselves, and the sweep fills in what the prose did not print:

npx degit@3.8.0 --force warrendeleon/react-native-module-federation#post-05-contracts /tmp/pokedex-ref-05
cp -R /tmp/pokedex-ref-05/. .

That fills in the package manifests, the packages' exports and TypeScript configuration, and the host, list and party edits the prose summarised.

One part of your tree does change. The version ladder is a demonstration, not a step the series builds on: 1.1.0 and 2.0.0 stay in your registry, but the repo carries DetailParams forward as { id: number }. So the sweep returns the contract source, the detail screen and the three app manifests to their 1.0.0 shape, and post 6 starts from there.

The finished code for this post is the post-05-contracts tag:

git checkout post-05-contracts

Next in the series: real data. The hardcoded Pokémon lists disappear, both copies, and every screen reads from one store fed by PokéAPI. That is where the hole in that sentence gets a proper answer, because a type checked at build time is no help against a value that shows up at runtime.

Sources

Module Federation 2.0 — the shared-module runtime, and the RUNTIME-006 reference
Verdaccio — the local npm registry both packages are published to
React Navigation — the native stack each remote now owns
npm semver ranges — what a caret does and does not accept, and what a peer range claims
react-native-module-federation — the companion repo, at the tag post-05-contracts

The host shell: federated remotes as tabs in React Native

Warren de Leon — Mon, 22 Jun 2026 13:03:33 +0000

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

Post 3 closed on a promise: the host stops being a single screen and becomes a real shell, owning the tab bar while each tab is a remote loaded at runtime. That's this post.

So far the host has loaded one screen from one remote, fullscreen, with nowhere else to go. A real app has a frame around its features: a tab bar, navigation, the parts that are always on screen. This post gives the host that job, and gives the second tab to a second remote.

The division of labour

One sentence carries the whole post: the host owns the frame, and remotes own the features inside it.

The host installs the navigation library, mounts the tab bar and decides which tabs exist. The remotes stay plain screens. They don't import a navigator, don't know they're in a tab, and don't know a second remote exists. Adding a feature should be boring: build another remote, add another tab, ship it.

Two teams can then own two tabs, build them separately and deploy them on their own schedules, because neither one has to compile against the other.

📊 Diagram: view it on warrendeleon.com

The starting point is post 3's finished state. If you built along, that's the code you already have. If not:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-03-shared-singleton

A second remote to fill a second tab

One tab is not a tab bar. So we add a second remote, party, the same way post 2 built the list remote: a fresh React Native app on Re.Pack, with no AppRegistry.registerComponent, exposing one screen. The exact route, mirroring post 2's list steps:

npx @react-native-community/cli@20.1.0 init Party --directory apps/party --version 0.85.3
( cd apps/party && npm install -D @callstack/repack@5.2.5 @rspack/core@2.0.5 @module-federation/enhanced@2.5.0 @swc/helpers@0.5.23 @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 )
cp apps/list/react-native.config.js apps/party/
cp apps/list/rspack.config.mjs apps/party/

Then give it the same near-empty container entry the list has: copy apps/list/src/index.js to apps/party/src/index.js. The root index.js keeps its registration for standalone runs; the federated entry is the one with nothing to do at startup.

Four fields change in the copied apps/party/rspack.config.mjs, and all four matter. Their finished values:

// output, near the top:
      uniqueName: 'PartyApp',

// inside the ModuleFederationPluginV2 options:
        name: 'partyApp',
        filename: 'partyApp.container.js.bundle',
        exposes: {
          './PartyScreen': './src/PartyScreen.tsx',
        },

uniqueName is the easy one to miss. uniqueName scopes webpack's chunk-loading globals, so two remotes shipping the same value collide inside the host's runtime.

The screen it exposes, apps/party/src/PartyScreen.tsx, holds six empty slots:

import React from 'react';
import { StyleSheet, Text, View } from 'react-native';
import { useSafeAreaInsets } from 'react-native-safe-area-context';

const SLOTS = [1, 2, 3, 4, 5, 6];

export default function PartyScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={[styles.screen, { paddingTop: insets.top + 24 }]}>
      <Text style={styles.title}>Party</Text>
      <Text style={styles.subtitle}>
        Your party is empty. Add up to 6 Pokémon from the Pokédex.
      </Text>
      <View style={styles.grid}>
        {SLOTS.map(slot => (
          <View key={slot} style={styles.slot}>
            <Text style={styles.slotNumber}>{slot}</Text>
          </View>
        ))}
      </View>
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24, backgroundColor: '#fff' },
  title: { fontSize: 28, fontWeight: '700' },
  subtitle: { fontSize: 14, color: '#6b7280', marginBottom: 24 },
  // alignItems: 'flex-start' stops the default stretch from overriding each slot's aspectRatio.
  grid: { flexDirection: 'row', flexWrap: 'wrap', gap: 12, alignItems: 'flex-start' },
  slot: {
    width: '47%',
    aspectRatio: 1,
    borderRadius: 12,
    borderWidth: 1,
    borderStyle: 'dashed',
    borderColor: '#e5e7eb',
    backgroundColor: '#f9fafb',
    alignItems: 'center',
    justifyContent: 'center',
  },
  slotNumber: { fontSize: 20, fontWeight: '600', color: '#9ca3af' },
});

Nothing fills those slots yet, and that's deliberate. The app has no store, so the party has nowhere to keep its members; that arrives with the state posts. Today the team owning this feature ships the smallest thing it can put in front of a user: a screen with a shape and no data behind it. A screen with no props and no state is still a feature the shell can load at runtime.

It reads the safe-area inset through useSafeAreaInsets, which is post 3's shared singleton earning its keep: the inset comes from the host's provider, measured once, and this remote reads it without carrying its own copy of the library.

Give it its own dev-server port so it doesn't collide with list on 8082. In apps/party/package.json:

"scripts": {
  "start:remote": "react-native start --config rspack.config.mjs --port 8083"
}

Now there are two remotes, on 8082 and 8083, each a screen waiting for a host.

The host gets navigation

In this build the tab bar belongs to the host, not the remotes. Install the navigation packages in the host only:

( cd apps/host && npm install @react-navigation/native@7.3.1 @react-navigation/bottom-tabs@7.18.0 react-native-screens@4.25.2 )

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

That pod install is not optional, and neither is a fresh native build afterwards. react-native-screens ships native code. Skip either step and the build stops with 'RNSViewInteractionAware.h' file not found, which reads like a broken library and is really a missing pod. It is the first native dependency the shell has taken on since post 2, and a preview of a constraint the series returns to later: JavaScript can arrive over the wire, native code cannot.

The federation part is post 3's contract read backwards. The shared singletons stay exactly what they were: react, react-native, and react-native-safe-area-context. React Navigation and react-native-screens are not shared, because no remote imports them.

Sharing everything by default is a defensible habit: one fewer decision per dependency, and no chance of forgetting something you needed. But sharing keeps two copies of a library from both loading in one runtime, and navigation never leaves the host, so there's no second copy to collide with.

Both sides touching a library is what makes sharing worth considering, not what makes it necessary. What decides it is whether the library carries identity: module-level state, a React context, a native module registered once per process. Post 3 is where that test came from, and post 7 is where it turns into a rule about who owns which boundary. Those have to be one copy. A value-only library that both sides import, with no instance to disagree about, is safe to duplicate and often cheaper to.

The shell

Rewrite apps/host/App.tsx. The host now owns a SafeAreaProvider, a NavigationContainer and a bottom tab navigator, and each tab's content is a lazily-loaded remote:

import React, { Suspense } from 'react';
import { ActivityIndicator, StyleSheet } from 'react-native';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { NavigationContainer } from '@react-navigation/native';
import { createBottomTabNavigator } from '@react-navigation/bottom-tabs';

const PokedexScreen = React.lazy(() => import('listApp/PokedexScreen'));
const PartyScreen = React.lazy(() => import('partyApp/PartyScreen'));

// A remote downloads the first time its tab is opened, so each tab renders behind a Suspense
// spinner. Wrapping once here keeps the lazy boundary out of the remotes.
function withSuspense(Remote: React.ComponentType) {
  return function Tab() {
    return (
      <Suspense fallback={<ActivityIndicator style={styles.loader} size="large" />}>
        <Remote />
      </Suspense>
    );
  };
}

const PokedexTab = withSuspense(PokedexScreen);
const PartyTab = withSuspense(PartyScreen);

const Tab = createBottomTabNavigator();

export default function App() {
  return (
    <SafeAreaProvider>
      <NavigationContainer>
        <Tab.Navigator screenOptions={{ headerShown: false }}>
          <Tab.Screen name="Pokédex" component={PokedexTab} />
          <Tab.Screen name="Party" component={PartyTab} />
        </Tab.Navigator>
      </NavigationContainer>
    </SafeAreaProvider>
  );
}

const styles = StyleSheet.create({
  loader: { flex: 1 },
});

Each tab is a remote behind React.lazy and Suspense, so the app fetches only the tab it opens on and leaves the other until you press it.

The host needs to know where the second remote lives. Add it to remotes in apps/host/rspack.config.mjs:

remotes: {
  listApp: `listApp@http://localhost:8082/${platform}/mf-manifest.json`,
  partyApp: `partyApp@http://localhost:8083/${platform}/mf-manifest.json`,
},

And tell TypeScript the shape of the new federated import, in apps/host/mf-modules.d.ts:

declare module 'partyApp/PartyScreen' {
  import type React from 'react';
  const PartyScreen: React.ComponentType;
  export default PartyScreen;
}

One more file, or the tests break before they run. React Navigation and react-native-screens ship ES modules, and the base React Native jest preset only sends React Native's own packages through Babel: its transformIgnorePatterns lists react-native, @react-native and @react-native-community, and nothing else. In apps/host/jest.config.js:

module.exports = {
  preset: '@react-native/jest-preset',
  transformIgnorePatterns: [
    'node_modules/(?!((jest-)?react-native|@react-native(-community)?|@react-navigation|react-native-screens)/)',
  ],
};

Run it

Four terminals now, one per remote, one for the host, plus the 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 host boots on the Pokédex tab and renders the list remote. Press Party and watch the 8083 terminal: its first request arrives at that moment, not at launch. The host fetches the container, runs it, and the empty grid appears.

🎞️ Animated demo: watch it on warrendeleon.com

Two features, built and served by two separate apps, sitting in one tab bar that belongs to neither of them.

Now break it

The host and the remote agree on one name in two separate files, and nothing checks that they still match. Break the agreement on purpose. In apps/party/rspack.config.mjs, rename the container:

new Repack.plugins.ModuleFederationPluginV2({
  name: 'partyRemote',        // the host still asks for partyApp
  filename: 'partyApp.container.js.bundle',

Restart the party dev server. An rspack config change doesn't hot-reload, so a plain refresh keeps serving the old manifest and hides the fault. Then relaunch the app and press Party:

[ Federation Runtime ]: Unhandled error. ([ScriptManager] Failed while resolving script locator:)
while loading "./PartyScreen" from webpack/container/reference/partyApp
  args: [ { scriptId: 'partyRemote', caller: undefined } ]
  originalError: [Error: No resolver was able to resolve script partyRemote]

Read it backwards and the chain is clear. The host asked for partyApp, because that's the key in its remotes map. It fetched the manifest at 8083, and the manifest declared a container called partyRemote. The runtime then looked for a script by that name, and the host has no partyRemote registered, so its resolver has nothing to match. Nothing was missing and nothing was offline. The rename was applied in one of the two files that have to agree, not both.

Notice where the failure surfaces. You get a red box, not the spinner: an uncaught error rather than a tab that waits forever. Suspense handles a promise that hasn't settled yet; it doesn't catch one that rejects. Nothing in this app watches for that, which is fine on a laptop with two dev servers and much less fine when the remote comes off a CDN (a content delivery network). Catching it properly needs an error boundary around the lazy tab. The series does not give that its own post, so treat it as work this shell still owes: the fallback and recovery story arrives with CDN delivery, where a missing remote stops being a laptop problem.

Put the name back, restart the server, press Party, and the grid returns.

What you built, and what's next

The host is a shell now. It owns navigation and the tab bar; each tab is a remote that was built and deployed on its own and loaded at runtime. The remotes stay simple: they render a screen and know nothing about how they are arranged. A third feature is a third remote and a third tab, with no change to the ones already shipped.

Land exactly on this post's finished state. The walkthrough prints the load-bearing files; manifests, configs 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-04-host-shell /tmp/pokedex-ref-04
cp -R /tmp/pokedex-ref-04/. .

The finished code for this post is the post-04-host-shell tag, if you cloned rather than building along:

git checkout post-04-host-shell

Next in the series: both tabs will want to open the same Pokémon detail screen. A screen two teams share is a component, not another deployable. The first thing two independently built apps have to agree on is what to pass it. Neither side can own that agreement, so it becomes a package: a contract, published and installed by version.

Sources

React Navigation — the bottom tab navigator the host shell is built on
Module Federation 2.0 — the name@url remotes that load each tab at runtime
react-native-screens — the native dependency React Navigation builds on
react-native-module-federation — the companion repo, at the tag post-04-host-shell