DEV Community: Warren de Leon

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

The shared-singleton contract in React Native Module Federation

Warren de Leon — Mon, 22 Jun 2026 12:40:25 +0000

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

The last post ended by pointing here: the shared-singleton contract, and the mistake that crashes the app on launch. This post covers both. What shared actually means, the three options that control it, and the failure a remote hits when it breaks the contract on a library with a native side. That failure is loud, immediate, and names itself, which makes it one of the easier ones to fix.

We pick up exactly where post 2 left off. If you built along then, stay on your own code. If not, start from post 2's finished state:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-02-first-remote

What "shared" actually meant in post 2

Post 2 declared react and react-native as shared singletons and moved on. Here is the host's half of that, from apps/host/rspack.config.mjs:

shared: {
  react: { singleton: true, eager: true, requiredVersion: pkg.dependencies.react },
  'react-native': {
    singleton: true,
    eager: true,
    requiredVersion: pkg.dependencies['react-native'],
  },
},

Three options do the work, and each one answers a different question.

singleton: true answers "how many copies may exist at runtime?" One. When the host and the remote both ask for react, Module Federation hands them the same instance instead of letting each load its own. This is the load-bearing option. React keeps its hooks state in module-level variables, so two copies of React in one app means two separate piles of state, and any hook called against the wrong pile throws.

eager: true answers "is this copy ready before the app's first line runs?" On the host, yes. A normal Module Federation entry is asynchronous: it sets up the share scope, then starts your code. React Native does not give you that gap. Its entry is synchronous, so the host marks its shared copies eager to load them into the share scope up front, before AppRegistry renders anything. The remote does not need eager, because by the time it loads, the host has already filled the scope.

requiredVersion answers "which versions count as the same?" It pins the acceptable range. Stating it explicitly is a habit worth keeping, but leaving it out is not the same as switching the check off. The one case where the check really does disappear is the failure this post ends on.

So far this is post 2 with the reasoning filled in. The contract starts to matter the moment a remote depends on a third library, not just React.

A real dependency: the safe area

React Native's built-in SafeAreaView is deprecated. The maintained replacement is react-native-safe-area-context, and it ships with the current React Native template, so both apps in the repo already have it. It is a good test of the contract because it works through React context: a SafeAreaProvider mounted near the root measures the device's safe area, and any component below reads it with useSafeAreaInsets.

In a federated app, the provider and the consumer live in different bundles. The host owns the shell, so the host mounts the provider. Rewrite apps/host/App.tsx:

import React, { Suspense } from 'react';
import { ActivityIndicator, StyleSheet } from 'react-native';
import { SafeAreaProvider } from 'react-native-safe-area-context';

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

export default function App() {
  return (
    <SafeAreaProvider>
      <Suspense fallback={<ActivityIndicator style={styles.loader} size="large" />}>
        <PokedexScreen />
      </Suspense>
    </SafeAreaProvider>
  );
}

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

The host no longer pads the screen itself. It provides the safe-area context and hands the whole canvas to the remote. Now the remote reads the inset and keeps its own title clear of the notch. Update apps/list/src/PokedexScreen.tsx:

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

const POKEMON = [
  { id: 1, name: 'Bulbasaur' },
  { id: 4, name: 'Charmander' },
  { id: 7, name: 'Squirtle' },
  { id: 25, name: 'Pikachu' },
  { id: 133, name: 'Eevee' },
];

export default function PokedexScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={[styles.screen, { paddingTop: insets.top + 24 }]}>
      <Text style={styles.title}>Pokédex</Text>
      <Text style={styles.subtitle}>Served by the list remote</Text>
      <FlatList
        data={POKEMON}
        keyExtractor={p => String(p.id)}
        renderItem={({ item }) => (
          <View style={styles.row}>
            <Text style={styles.number}>#{String(item.id).padStart(3, '0')}</Text>
            <Text style={styles.name}>{item.name}</Text>
          </View>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24, backgroundColor: '#fff' },
  title: { fontSize: 28, fontWeight: '700' },
  subtitle: { fontSize: 14, color: '#6b7280', marginBottom: 16 },
  row: {
    flexDirection: 'row',
    paddingVertical: 12,
    borderBottomWidth: StyleSheet.hairlineWidth,
    borderBottomColor: '#e5e7eb',
  },
  number: { width: 56, color: '#9ca3af', fontVariant: ['tabular-nums'] },
  name: { fontSize: 16, fontWeight: '500' },
});

There is now a context handshake that crosses the bundle boundary: the provider is in the host, the useSafeAreaInsets call is in the remote. For that to connect, both apps need the same SafeAreaProvider, from the same copy of the library. A React context is identified by the object that creates it. Two copies of the library make two different context objects, and a consumer reading copy B will never see a provider mounted from copy A.

That is what the contract is for. Add the library to shared in both configs as a singleton. The host (apps/host/rspack.config.mjs), eager like its other shared copies:

shared: {
  react: { singleton: true, eager: true, requiredVersion: pkg.dependencies.react },
  'react-native': {
    singleton: true,
    eager: true,
    requiredVersion: pkg.dependencies['react-native'],
  },
  'react-native-safe-area-context': {
    singleton: true,
    eager: true,
    requiredVersion: pkg.dependencies['react-native-safe-area-context'],
  },
},

And the remote (apps/list/rspack.config.mjs), singleton but not eager:

shared: {
  react: { singleton: true, requiredVersion: pkg.dependencies.react },
  'react-native': {
    singleton: true,
    requiredVersion: pkg.dependencies['react-native'],
  },
  'react-native-safe-area-context': {
    singleton: true,
    requiredVersion: pkg.dependencies['react-native-safe-area-context'],
  },
},

Start both dev servers and run the host (the three-terminal routine from post 2). The Pokédex renders with its title sitting below the Dynamic Island, padded by the inset the remote read from the host's provider. One library, one provider, one context object, shared across two apps that were built and shipped on their own.

Now break it

Delete one entry. Take react-native-safe-area-context out of the remote's shared block, leaving it in the host's. This is the realistic version of the mistake: the host author shared it, the remote author forgot. Restart the remote's dev server and reload the host.

The app does not render a slightly-wrong screen. It red-boxes on launch:

Uncaught Error: Tried to register two views with the same name RNCSafeAreaProvider

Here is why it is loud rather than quiet. react-native-safe-area-context is not pure JavaScript. It ships a native view, RNCSafeAreaProvider, that it registers with React Native's view registry at startup. The host's copy registers it once. When the remote drops the share, it bundles its own copy, and that copy tries to register the same native name a second time. React Native keeps one registry per app and refuses the duplicate. The crash fires before a single Pokémon reaches the screen.

📊 Diagram: view it on warrendeleon.com

This is the pattern for a library whose JavaScript registers something with the native layer, the way safe-area context registers its provider view: a navigation library, a gesture handler, anything that calls requireNativeComponent or keeps native-facing identity in module scope. Share it from one place and it works. Let two bundles each carry their own and both copies register the same native view, and they collide early and obviously. Not every native-backed library fails like this: a thin wrapper that only calls into a native module can survive duplication, because nothing identity-shaped collides. The ones that break register views or hold state, and the error even names the view, so the fix points back at the missing share.

Put that entry back in the remote's shared block, and the app builds and runs again.

React itself fails just as loudly, for a different reason. Drop react from a remote's shared and the remote bundles its own React. The first hook the remote runs gets checked against the wrong copy, and you get the familiar Invalid hook call red box. Same lesson: a library that keeps identity in module scope does not survive being loaded twice. That is a property of those libraries rather than a rule the runtime enforces everywhere.

The failure that does stay quiet

One case earns the "quiet" label, and it is requiredVersion, though not the way you might expect. Drop the field and, most of the time, nothing changes: Module Federation falls back to the version recorded for that dependency in the consuming package's own package.json, so a range still gets checked. The quiet failure needs one more ingredient: no version for the bundler to fall back on. That happens when the shared package is missing from the consumer's package.json, or when the package's layout stops the bundler reading a version for it (a trap the contract-package post walks straight into). With no range from either source, Module Federation has nothing to check: it loads whichever copy wins and runs on. That is the one to be careful with, because it builds and ships clean, and only shows up once two teams end up on different versions of a dependency. Pin requiredVersion explicitly, as the configs above do, and the check stops depending on what the bundler managed to infer.

So the general rule is the reassuring one. Most ways of breaking the shared contract announce themselves on launch. The quiet one is narrow, and a single field closes it.

What you built, and what's next

The host owns one SafeAreaProvider. The remote reads its insets across the bundle boundary, because both apps resolve to one shared copy of the library. You saw the contract hold, then watched it crash when a remote forgot its half, and you know now that the crash is the friendly outcome.

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

Next in the series: 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.

Sources

react-native-safe-area-context: the maintained safe-area library, and the RNCSafeAreaProvider native view in the crash
Module Federation 2.0: the shared contract: singleton, eager, and requiredVersion
react-native-module-federation: the companion repo, at the tag post-03-shared-singleton

Your first federated remote in React Native

Warren de Leon — Mon, 22 Jun 2026 12:39:49 +0000

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

The first post made the case for Module Federation. This one builds the smallest real version of it: two separate React Native apps, where one app (the host) loads a screen from the other (a remote) while it's running. We go from an empty folder to a running app, every step shown.

The finished code is in the companion repo at the tag for this post, so you can clone it and diff against your own if something drifts:

git clone https://github.com/warrendeleon/react-native-module-federation
cd react-native-module-federation
git checkout post-02-first-remote

This is what you'll have at the end. The list of Pokémon on screen lives in, and is served by, a different app from the one running:

Two apps

A federation needs a host and at least one remote. Create two fresh React Native apps:

mkdir react-native-module-federation && cd react-native-module-federation
npx @react-native-community/cli@20.1.0 init Host --directory apps/host --version 0.85.3
npx @react-native-community/cli@20.1.0 init List --directory apps/list --version 0.85.3

The versions are pinned on purpose: this series is built and verified on RN 0.85.3 with Re.Pack 5.2.5, on the iOS simulator. A newer RN scaffold will probably work, but you'd be first to find out. (Android runs the same configs, with one wrinkle: the localhost manifest URLs need adb reverse, or 10.0.2.2 in their place.)

host is the shell the user launches. list is a feature that will be loaded into it at runtime.

Put both on Re.Pack

React Native ships with Metro. Module Federation 2.0 runs on Re.Pack (Rspack underneath), so the first job is to swap the bundler. The steps are identical in both apps.

Install the bundler and the federation packages in each app, from the repo root:

( cd apps/host && 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 )
( cd apps/list && 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 )

An unpinned install answers to whatever the registry serves on the day you run it, which is why every version here is named. The CLI trio sits past the version the scaffold installs, which clears the fixable npm audit advisories the template ships with.

@swc/helpers is the easy one to miss. Re.Pack compiles your code with SWC (the Speedy Web Compiler, a Rust-based alternative to Babel that it uses underneath). When SWC compiles modern syntax down, it emits require("@swc/helpers/…") calls to a small shared helper library rather than inlining the same boilerplate everywhere. Miss the package and the build fails with a screen of "can't resolve" errors that give no hint of the real cause.

Now point the React Native CLI at Re.Pack. In both apps, add react-native.config.js:

// apps/host/react-native.config.js  AND  apps/list/react-native.config.js
module.exports = {
  commands: require('@callstack/repack/commands/rspack'),
};

That single file is what makes react-native start and react-native bundle use Rspack instead of Metro. The bundler is swapped. The host and the remote differ in the rspack.config.mjs each one gets, and that file is where federation is configured.

The remote: expose a screen

In this project a remote is an app with no AppRegistry.registerComponent. That is a choice about how these remotes are built rather than a definition of the term: a remote can register a root component and run standalone too, and some setups keep that for development. Here it doesn't boot itself, it waits to be pulled into a host, and it declares a name and what it hands out.

First the screen it hands out, apps/list/src/PokedexScreen.tsx. Plain React Native on purpose, this post is about loading it, not styling it:

import React from 'react';
import { FlatList, StyleSheet, Text, View } from 'react-native';

const POKEMON = [
  { id: 1, name: 'Bulbasaur' },
  { id: 4, name: 'Charmander' },
  { id: 7, name: 'Squirtle' },
  { id: 25, name: 'Pikachu' },
  { id: 133, name: 'Eevee' },
];

export default function PokedexScreen() {
  return (
    <View style={styles.screen}>
      <Text style={styles.title}>Pokédex</Text>
      <Text style={styles.subtitle}>Served by the list remote</Text>
      <FlatList
        data={POKEMON}
        keyExtractor={p => String(p.id)}
        renderItem={({ item }) => (
          <View style={styles.row}>
            <Text style={styles.number}>#{String(item.id).padStart(3, '0')}</Text>
            <Text style={styles.name}>{item.name}</Text>
          </View>
        )}
      />
    </View>
  );
}

const styles = StyleSheet.create({
  screen: { flex: 1, padding: 24, backgroundColor: '#fff' },
  title: { fontSize: 28, fontWeight: '700' },
  subtitle: { fontSize: 14, color: '#6b7280', marginBottom: 16 },
  row: {
    flexDirection: 'row',
    paddingVertical: 12,
    borderBottomWidth: StyleSheet.hairlineWidth,
    borderBottomColor: '#e5e7eb',
  },
  number: { width: 56, color: '#9ca3af', fontVariant: ['tabular-nums'] },
  name: { fontSize: 16, fontWeight: '500' },
});

The container's entry point, apps/list/src/index.js, is almost empty. A remote registers no root component, so it has nothing to do at startup:

// apps/list/src/index.js
export {};

Now the config, apps/list/rspack.config.mjs:

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';
import pkg from './package.json' with { type: 'json' };

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default Repack.defineRspackConfig(env => {
  const { mode, platform } = env;

  return {
    mode,
    context: __dirname,
    entry: './src/index.js',
    resolve: {
      // Lets the resolver read each package's `exports` map, which the Module Federation
      // runtime needs for subpath imports like '@module-federation/runtime/helpers'.
      ...Repack.getResolveOptions({ enablePackageExports: true }),
    },
    output: {
      path: `${__dirname}/build/[platform]`,
      uniqueName: 'ListApp',
    },
    module: {
      rules: [
        {
          test: /\.[cm]?[jt]sx?$/,
          type: 'javascript/auto',
          use: { loader: '@callstack/repack/babel-swc-loader', parallel: true, options: {} },
        },
        ...Repack.getAssetTransformRules(),
      ],
    },
    plugins: [
      new Repack.RepackPlugin({
        extraChunks: [
          { include: /.*/, type: 'remote', outputPath: `build/${platform}/remote` },
        ],
      }),
      new Repack.plugins.ModuleFederationPluginV2({
        name: 'listApp',
        filename: 'listApp.container.js.bundle',
        exposes: {
          './PokedexScreen': './src/PokedexScreen.tsx',
        },
        dts: false,
        shared: {
          react: { singleton: true, requiredVersion: pkg.dependencies.react },
          'react-native': {
            singleton: true,
            requiredVersion: pkg.dependencies['react-native'],
          },
        },
      }),
    ],
  };
});

Three things in there matter. exposes maps a public key, ./PokedexScreen, to a file. That key is the remote's entire public surface. shared declares react and react-native as singletons, so the remote renders against the host's one copy instead of bundling its own (two Reacts in one runtime would break hooks). And enablePackageExports: true is not optional: without it the federation runtime can't resolve its own subpath imports and the build fails.

Add a dev-server script to apps/list/package.json:

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

Start it:

cd apps/list && npm run start:remote

It serves a manifest at http://localhost:8082/ios/mf-manifest.json describing the container and the screen it exposes. Open that URL and you'll see ./PokedexScreen listed. The remote renders nothing on its own, it's a feature waiting for an app.

The host: load the remote

The host is an ordinary React Native app. Its apps/host/rspack.config.mjs consumes the remote:

import path from 'node:path';
import { fileURLToPath } from 'node:url';
import * as Repack from '@callstack/repack';
import pkg from './package.json' with { type: 'json' };

const __dirname = path.dirname(fileURLToPath(import.meta.url));

export default Repack.defineRspackConfig(env => {
  const { mode, platform } = env;

  return {
    mode,
    context: __dirname,
    entry: './index.js',
    resolve: {
      ...Repack.getResolveOptions({ enablePackageExports: true }),
    },
    output: {
      path: `${__dirname}/build/[platform]`,
      uniqueName: 'Host',
    },
    module: {
      rules: [
        {
          test: /\.[cm]?[jt]sx?$/,
          type: 'javascript/auto',
          use: { loader: '@callstack/repack/babel-swc-loader', parallel: true, options: {} },
        },
        ...Repack.getAssetTransformRules(),
      ],
    },
    plugins: [
      new Repack.RepackPlugin(),
      new Repack.plugins.ModuleFederationPluginV2({
        name: 'host',
        filename: 'host.container.js.bundle',
        remotes: {
          // name@url: the host knows listApp lives at this manifest URL. In dev that is the
          // remote's own dev server on :8082.
          listApp: `listApp@http://localhost:8082/${platform}/mf-manifest.json`,
        },
        dts: false,
        shared: {
          react: { singleton: true, eager: true, requiredVersion: pkg.dependencies.react },
          'react-native': {
            singleton: true,
            eager: true,
            requiredVersion: pkg.dependencies['react-native'],
          },
        },
      }),
    ],
  };
});

The name@url line is the whole wiring: the host knows a remote called listApp sits at that manifest URL. The host's shared adds eager: true, because the host is the one copy everyone renders against, and eager makes the share scope ready before the synchronous app entry runs, so no bootstrap file is needed.

Now load it. Replace apps/host/App.tsx:

import React, { Suspense } from 'react';
import { ActivityIndicator, StyleSheet } from 'react-native';
import { SafeAreaProvider, SafeAreaView } from 'react-native-safe-area-context';

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

export default function App() {
  return (
    <SafeAreaProvider>
      <SafeAreaView style={styles.root}>
        <Suspense fallback={<ActivityIndicator style={styles.loader} size="large" />}>
          <PokedexScreen />
        </Suspense>
      </SafeAreaView>
    </SafeAreaProvider>
  );
}

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

listApp/PokedexScreen is not a package on disk. It's the listApp from the host's remotes, then the ./PokedexScreen that remote exposed. At runtime, Module Federation turns that import into "fetch listApp's container from its URL, start it, return its PokedexScreen export". Because it's a dynamic import returning a promise, it fits directly into React.lazy with a Suspense spinner while the remote downloads.

TypeScript doesn't know that specifier, so tell it the shape. Add apps/host/mf-modules.d.ts:

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

ScriptManager: the part that's different on native

Everything above would look familiar to anyone who's done Module Federation on the web. React Native is where it diverges.

On the web, import('listApp/PokedexScreen') ends in the browser fetching a script over HTTP and the engine running it. A browser does that constantly. Loading code from a URL is routine for it. A React Native runtime has no equivalent. No DOM, no <script> tag, no built-in way to pull in more code on demand once the app has booted. A standard RN app is one self-contained bundle, loaded at launch, with nothing in it that knows how to go and fetch another chunk later.

Re.Pack fills that gap with ScriptManager: the piece that turns a request the federation runtime makes ("I need listApp's container") into the real steps: work out the URL, fetch the script, hand it to the engine to run, cache it. On native, every federated import goes through it.

The good news for this post: in dev you write none of it. The Module Federation plugin you already added auto-wires ScriptManager and a default resolver that knows how to reach the remote's dev server. So the full loop is just:

📊 Diagram: view it on warrendeleon.com

When you move to production, ScriptManager is where the real work is: resolving versioned CDN URLs, verifying a signature before running anything, falling back to an embedded copy when the network fails. All later in the series. For now it's enough to know it's the bridge between "import a remote" and "code arrives over the wire and runs" that the browser gave web federation for free.

Run it

The host is the only app whose native project gets built; the remote keeps its ios/ folder from the scaffold, but nothing ever compiles it. So pods are installed for the host only:

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

Then, in three terminals:

# 1. the remote's dev server (leave the one from earlier running, or start it)
cd apps/list && npm run start:remote     # :8082

# 2. the host's dev server
cd apps/host && npm start                # :8081

# 3. build and launch the host on a simulator
cd apps/host && npm run ios

The host boots, shows the spinner briefly while it fetches listApp from :8082, then renders the Pokédex screen, served by a separately built app. Separately built and separately deployed, but not separately installed: what ships on its own is the remote's JavaScript bundle, and it runs inside the host's binary.

To prove they really are separate, stop the list dev server and reload the host. The screen can't load. Making that degrade to something safe, an offline copy built into the host, is its own post later in the series; the shared store post meets a softer version of the same failure much sooner. Right now the basic loop is what matters, and it runs.

What you built, and what's still minimal

You have two apps that build and deploy on their own, joined at runtime. The host imports a screen by name, and the code arrives over the network and runs inside it. The remote compiled nothing into the host.

Two things were kept deliberately minimal, each its own post:

The shared libraries. react and react-native are shared so the remote renders against the host's copy. The full contract, eager versus lazy, version skew, and the mistake that crashes the app on launch, is the next post.
Everything production needs. Versioned CDN loads, signing, an offline fallback, and what happens when a remote is gone. The second half of the series.

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

Sources

Re.Pack: the React Native bundler that wraps Rspack and provides ScriptManager and Module Federation support
Module Federation 2.0: the runtime architecture behind name@url remotes and exposes
react-native-module-federation: the companion repo, at the tag post-02-first-remote