DEV Community: Warren de Leon

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 it, 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?

Three kinds of state now live in this app, and each has a different owner.

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. Nobody owns a cache entry; PokéAPI does.

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 seam 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 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.

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 sabotage at the end of this post 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. Publish:

cd packages/contracts
npm install && npm publish

+ @pokedex/contracts@3.1.0

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.0, and install honours the lockfile even though the caret would accept 3.1.0. 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, usefully, on camera. 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'.

Three majors of the detail package have happened around this app while it wasn't looking. 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 eight-line container the list app wrote in post 6. A container needs data, and that becomes a wall of its own two sections from now. 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, and the match works across separately built apps because both sides hold the same action creator object. Contracts is a singleton, so party/add is one creator, not two that happen to share a string. 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 two things import it: the party screen (which also imports remove), and nothing else. 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, one line at module scope:

// Screens load on demand; state modules load at boot.
import('partyApp/partySlice').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 result: 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. State loads at boot, because state has to exist before the first dispatch aimed at it.

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, 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 count = useSelector((s: PartySliceShape) => s.party?.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}
      addLabel={full ? 'Party is full' : 'Add to party'}
    />
  );
}

Read what that tap does. A screen owned by the Pokédex team dispatches a creator owned by the contract, and the 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. 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: every consumer of a shared package moves in lockstep with its releases, so the Pokédex team's endpoint changes would now gate the party team's ship dates. 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`

The second injection is skipped: loudly in development, silently in production, where that guard compiles out. Both apps share whichever definition loaded first, and with it that definition's cache entries: open Bulbasaur from the Pokédex and then from the party, and the second open is a cache hit, one fetch total. Identical definitions make the skip harmless; here it is close to the point. The trap is drift: if the two copies ever diverge, whichever loads first silently wins for both, and the dev-console noise you learned to ignore was the only warning. The rule, then: inject an identical definition and let the skip deduplicate, pass overrideExisting: true only as a deliberate act, or name your endpoint something of your own.

Now break it

The claim to attack: the shell's boot import is what makes the party slice reliable, rather than merely polite. Comment it out:

// import('partyApp/partySlice').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 fell into a void that used to be an error.

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. That class of bug is why the pattern is a boot import and not a hope: screens load on demand, state modules load at boot, and the difference is whether the store's shape depends on the user's route history.

Restore the line, relaunch, and the same tap ticks the counter to 1/6.

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 already reading 0/6: the boot import at work before any tab of the party's has rendered. 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, injected at boot into a store the host wired around the contract's rootReducer. 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 never has this argument. One team, one repo, one store. 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 below 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 1. Does 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, three state flags and a retry callback, and renders them. That is the whole surface, and the whole arrangement is two lines 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 2. Does this component know where its data comes from? A yes means the boundary is misdrawn: 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. If it needs a provider, a client or a store to exist first, it is not a component yet.

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, how it parses, 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 3. Does this definition live with its domain? Machinery with no domain knowledge in it is shared; an endpoint, a parser, a schema for one domain's data travels with the domain.

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. Every change to it lands on both teams, so every change needs both teams' agreement. 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. The series has already photographed what a versioned dependency between teams looks like when the schedules diverge. 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 has a hard limit, because both parse the same wire format from the same backend. When the duplication grows past a file (five endpoints, ten), the answer changes, and the next section 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 4. Does 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, every consumer was affected the moment it changed; the generated client just surfaces the fact at build time instead of in production. 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 5. Can 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 precondition dissolves. 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, parsers and schemas travel with the domain.
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. A platform team of one cannot review at the pace five teams contribute, and inner source turns back into the queue it was meant to replace. 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({
  results: z.array(z.object({ name: z.string(), url: z.string() })),
});

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+)\/?$/);
  return match ? Number(match[1]) : 0;
}

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 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.0. packages/contracts/package.json:

{
  "name": "@pokedex/contracts",
  "version": "3.0.0",
  "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.0

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.0 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 sabotage near the end of this post 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'],
},

Both Redux packages state version by hand, and @pokedex/contracts does not. Post 5 found the rule: rspack reads the version out of the package it is sharing, except for a package resolved through an exports map, where it silently skips the provide instead. @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.0"
"@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.0 )
( cd apps/list && npm install @reduxjs/toolkit@^2.12.0 react-redux@^9.3.0 @pokedex/contracts@^3.0.0 )

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 an eight-line container. 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. The contract keeps paying for itself in places the last post never predicted.

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.

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.

The punchline

Declarative tags scale to teams. String-based keys don't. That's the comparison in one line, and the rest of this post is the proof.

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."

The scenario

Dealing team ships an executeTrade mutation. Portfolio team has a getPortfolio query that returns the user's holdings. When the trade succeeds, the portfolio cache is stale, and something has to mark it for refetch.

With RTK Query tags

Portfolio team declares what their query holds:

getPortfolio: builder.query({
  query: (id) => `/portfolio/${id}`,
  providesTags: ['Portfolio'],
}),

Dealing team declares what their mutation affects:

executeTrade: builder.mutation({
  query: (order) => ({ url: '/trades', method: 'POST', body: order }),
  invalidatesTags: ['Portfolio'],
}),

When the mutation succeeds, the library walks its cache, finds queries that provide the Portfolio tag, and refetches the ones currently mounted. Dealing team never reads portfolio's code. They don't need to know what query key portfolio 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 'Portfolio'. 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 dealing team writes:

queryClient.invalidateQueries({ queryKey: ['portfolio'] });

For that line to be correct, the dealing team has to know the portfolio team's exact query key shape. They go look at portfolio's code, find the useQuery call, read the key, and copy it into their own invalidation.

The teams are coupled to the same string 'portfolio', but the coupling lives in a different place. It's a magic string in the dealing team's mutation handler, with no contract pointing back to portfolio's query.

What happens when teams drift

Both approaches produce the same outcome when teams stay coordinated. The cached portfolio data refetches, the UI updates, the user sees fresh holdings. The approaches diverge when coordination slips.

Take a rename. The portfolio team is refactoring. The domain term has shifted. What they used to call "portfolio" is now called "holdings" across the API, the docs, and the team's day-to-day language. They rename the query key:

// before
useQuery({ queryKey: ['portfolio', accountId], queryFn: fetchPortfolio });

// after
useQuery({ queryKey: ['holdings', accountId], queryFn: fetchHoldings });

They ship.

In an RTK Query world with tags, the rename has no effect on the dealing team's invalidation. Tags are independent of query keys. The portfolio team's query still provides 'Portfolio'. The dealing team's mutation still invalidates 'Portfolio'. The wiring holds.

In a TanStack Query world with keys, the rename breaks the dealing team silently. invalidateQueries({ queryKey: ['portfolio'] }) 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 portfolio cache 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 straight away because every endpoint referencing the old name is suddenly invalid.

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.

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.

What this means in practice

A few things to take from this.

If your app is one team and one codebase, 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.

If your app has multiple teams and they ship independently, 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.

If you're early in a library choice and federation or multi-team coordination is on the horizon, 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 when its state posts land. 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.

These two posts 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, retry and refetch-on-focus come with it:

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. If your team already lives in Redux, RTK Query is the shorter road, because it drops the server-state machinery into the store you already run. Coming to a fresh app with no Redux commitment, TanStack Query and Zustand are two focused tools that compose without treading on each other. And on 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?

The question only gets sharper once features stop sharing a codebase. When each ships as its own app and loads at runtime, whose cache is authoritative stops being a convenience and becomes something you have to coordinate. That is where the Module Federation series picks back up, and it is far easier to reason about once the plain-app version is second nature.

Before then, the next post stays on the server half and looks at a single difference between these tools: 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. The closing act breaks the agreement on purpose, three rungs up a version ladder, and ends 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, so all three join the shared singleton maps on every side: the map is a record of what more than one party imports, and three more packages just crossed that line. Two of the new entries state version by hand:

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

Rspack normally reads the version out of the package it is sharing, but it cannot for a package resolved through an exports map, and React Navigation has one. 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. A single screen never earns that overhead, and a codebase that hands one out per screen is on its way to shipping an app per screen.

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: a boundary is a team's domain, not a screen.

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. Keep that sentence; the end of this post is built on it.

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 the end of this post shows the price.

All three apps install both packages. A real install, by version, from the registry:

npm install @pokedex/contracts@^1.0.0 @pokedex/detail@^1.0.0

Every app unpacks its own copy into node_modules, holding the version it asked for. Four copies of the contract across the codebase 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.

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. Which is where the hole in that sentence gets a proper answer, because a type that was 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
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. Create it next to the others, install its dependencies exactly as you did for list, and copy list's rspack.config.mjs across.

Four fields change, and all four matter: the plugin name (partyApp), the container filename (partyApp.container.js.bundle), the exposed screen (./PartyScreen), and output.uniqueName ('PartyApp'). That last one 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

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 @react-navigation/bottom-tabs react-native-screens

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

react-native-screens ships native code, so that pod install isn't optional and neither is a fresh native build afterwards. Skip it 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.

The rule runs both ways: share a library when code on both sides touches it, and only then.

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, and that comes later in the series.

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.

The finished code for this post is the post-04-host-shell tag, so you can diff it against your own:

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
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, read straight from the host's package.json. Leave it out and Module Federation cannot tell whether the host's copy satisfies the remote, so it stops treating them as interchangeable. More on that at the end, because that is the one failure here that does stay quiet.

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 any library with a native side: a navigation library, a gesture handler, a storage module. Share it from one place and it works. Let two bundles each carry their own and they collide at the native layer, early and obviously. 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: the runtime will not quietly run two copies of something that was built to be one.

The failure that does stay quiet

One case earns the "quiet" label, and it is requiredVersion. Keep singleton: true but drop requiredVersion, and the app still builds and runs. The singleton rule forces one copy, so in development, with one version installed, nothing visibly changes. The danger only appears when the host and a remote are built against genuinely different versions of a pure-JavaScript shared package. With no version range to check, Module Federation cannot warn that they disagree. 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 from package.json, as the configs above do, and you turn that silent drift into a warning you can read.

So the general rule is the reassuring one. Most ways of breaking the shared contract crash on launch, name the thing you got wrong, and cost you a few minutes. The quiet one is narrow and you can close it with a single field.

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.

The finished code for this post is the post-03-shared-singleton tag, so you can diff it against your own:

git checkout post-03-shared-singleton

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
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:

npm install -D @callstack/repack @rspack/core \
  @module-federation/enhanced @swc/helpers

@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. What differs between host and remote is the rspack.config.mjs each one gets, which is where federation is configured.

The remote: expose a screen

A federated remote is an app with no AppRegistry.registerComponent. It doesn't boot itself, it waits to be pulled into a host. 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 completely separate app.

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. 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.

Next: the shared-singleton contract, and the mistake that crashes the app on launch.

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

Why Module Federation in React Native

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

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

The short version: Module Federation lets a React Native app load its features at runtime, so each one can be deployed and updated on its own instead of riding in a single app-store release. That buys independent deploys and over-the-air fixes. It also hands you a distributed-systems problem that used to be a bundler's job. This series builds a working federated setup from scratch on a small Pokédex app. This first post is about whether you should.

Every feature ships in every release

A standard React Native app is one bundle. Organise it well, by feature rather than by type, and it changes nothing here: the login screen, the settings page, the report nobody opens, all compiled together, all gated behind the same store review, all riding the same release train. A one-line fix to one screen waits for the whole app to be rebuilt, resubmitted, and approved.

For a small app with one team, that's fine. The release train is cheap and everyone is on it anyway. For a large app with several teams, it's expensive. One team's urgent fix sits behind another team's half-finished feature because they share a binary. The release turns into a negotiation, and the cadence drops to the slowest contributor on the train.

That coupling is the thing Module Federation is trying to undo. Not bundle size, not build speed, those are nice side effects. The real prize is breaking the link between "I changed my feature" and "the whole app has to ship".

What it actually is

A federated app has a host and a set of remotes. The host is the shell: navigation, the tab bar, the shared libraries, the bits that are always there. The remotes are the features, and each one is built and deployed on its own, then pulled in at runtime from a URL.

The host doesn't compile the remotes into itself the way a single bundle does. A copy of each still rides inside the app binary as a fallback, the reviewed app has to work on its own, with no network, but that copy is only the guaranteed minimum. The live version comes from the CDN and updates without a release. The host also provides the heavy shared libraries once, React, the navigation stack, the styling layer, so each remote consumes the host's copy instead of carrying its own. A remote becomes a small payload of feature code that snaps into a shell already holding everything underneath it.

📊 Diagram: view it on warrendeleon.com

In practice that runs on Re.Pack (Rspack underneath) with Module Federation 2.0. The mechanics are a later post. For now the mental model is enough: a shell that loads features at runtime, from the network or a baked-in fallback, against a contract about what the shell provides.

What it buys you

Independent deploys. A feature team ships when their feature is ready, not when the train leaves. The release stops being a shared resource everyone queues for.

Over-the-air fixes. A bug in one remote is a re-upload of that remote, not a store submission. The fix is live in minutes, and each user picks it up on their next launch, within the platform rules (more on those below).

Faster starts. Features that aren't needed at launch load lazily, so less JavaScript runs on the critical path. The download itself doesn't shrink if you ship an offline fallback, the binary still carries every remote, but startup can.

Team autonomy at scale. Each feature owns its own build, its own deploy, its own cadence. The architecture stops forcing teams into lockstep.

If none of those are pains you actually feel, the rest of this post is your exit. Federation solves coupling. No coupling, no reason to pay for the solution.

What it costs

This is the part the enthusiastic posts skip, so it's the part worth slowing down on.

The shared-singleton contract. The host provides one React, one navigation library, one styling layer, and every remote renders against those. The moment a remote needs a newer version of a shared library than the host carries, you have a version-skew problem. Unhandled, the runtime negotiates down to the host's copy and the remote breaks on an API that copy doesn't have. It's solvable, the series builds the fix, but solving it is the cost: the shared set becomes a contract you own and have to keep compatible, work the compiler used to do for free.

The compatibility burden, especially for old app versions. Users don't all update. A binary someone installed months ago has the shared libraries frozen at whatever shipped then. Push a remote that needs newer ones and you break exactly the people who haven't moved. So you end up keeping old remote versions available for old app versions, the same discipline as keeping an old API endpoint alive until the last client stops calling it. That is not bundler work. That is running a versioned service.

Integrity. Once your app downloads and runs code from a URL, that URL is an attack surface. You have to sign what you ship and have the device verify it before executing, or a compromised host can hand your users whatever it likes. Then you have to protect the choice of version too, so a replayed or rolled-back manifest can't quietly serve an old, vulnerable build. Security that a single signed binary gave you for free, you now build yourself.

Platform rules. What makes OTA legal at all is Apple's Developer Program License Agreement (section 3.3.1(B)): an app may run downloaded interpreted code like JavaScript, as long as it doesn't change the app's primary purpose. Review guideline 2.5.2 is the matching constraint, the binary you submit still has to work on its own and can't pull down code that introduces or changes features. No shipping major unreviewed features over the air. Federation lives inside those lines, it doesn't erase them.

Operational surface. A CDN to run, caches to invalidate, rollbacks to script, failures to monitor. When a remote won't load, the app has to degrade to something safe instead of showing a blank screen. That safety net is real engineering, and it's on you.

Put together: Module Federation is a distributed-systems problem wearing a bundler's clothes. The bundler part is bounded, you set it up and it's done. The systems part, signing, versioning, compatibility, fallback, is the actual work, and it never fully ends.

When it's worth it

Reach for it when all three are true:

Multiple teams are stepping on each other in a shared release.
The coupling is a measured cost, slower cadence, blocked fixes, not a theoretical one.
Someone can own the platform, the CDN, the signing, the version contract, the fallback layer, as ongoing work.

Skip it when the app is small, one team owns it, and a store release every couple of weeks is no burden. The complexity you'd take on dwarfs the coupling you'd remove. Code splitting alone, async chunks without the runtime-remote machinery, gets you the lazy-loading and faster-start win at a fraction of the cost, and it's a sensible stop short of full federation.

Federation is a scaling tool. Adopt it because you've hit the scale that justifies it, not because the architecture is interesting. It is interesting. That's the trap.

What the rest of this series does

From here it's hands-on. We build a federated setup on a small Pokédex app and take it the whole way:

a host and a first remote, loading at runtime
the shared-singleton contract, and the trap that fails it silently
loading remotes from a CDN, with an offline fallback baked into the app
signing remotes and the version manifest so a tampered or replayed build can't run
and the hard one, making sure an old app version never gets a remote it can't run, and never crashes when one goes missing

By the end you'll have a working version of everything this post just warned you about, and a clear sense of whether it's a trade your app should make.

Sources

Re.Pack: the React Native bundler that wraps Rspack and ships Module Federation support
Module Federation 2.0: the runtime architecture
Rspack: the Rust-based bundler under Re.Pack
App Store Review Guidelines, 2.5.2: Apple's self-contained-apps constraint; the interpreted-code permission lives in the Developer Program License Agreement, 3.3.1(B)

Why I use feature-first project structure in React Native

Warren de Leon — Mon, 25 May 2026 07:30:23 +0000

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

The short version: below roughly five features with their own state, type-first folders (screens/, hooks/, services/) are fine. Above that, the same layout starts costing you more than it saves. This post is about why, and where the line sits.

85 files for one feature

That's how many TypeScript files my Auth feature has. Six screens, a Redux store, a React context, a custom hook, PIN components with Storybook stories, form validation schemas against a common password blacklist, rate limiting, a lockout service, and tests at every level.

In most React Native projects, those 85 files would be scattered across seven different folders. Screens in one place, hooks in another, the store slice somewhere else, validation in yet another. To understand how authentication works, you'd open seven folders and mentally reconstruct the relationships between files that sit nowhere near each other.

That layout looks tidy at three or four screens. Past that, the relationships go invisible. The hook for a feature lives nowhere near the screen that uses it. The validation rules sit in a separate folder from the form they validate. Reviewing a feature means scanning multiple alphabetised lists looking for the pieces.

The type-first layout, and why it's the default

You know this one:

src/
├── screens/
│   ├── LoginScreen.tsx
│   ├── ProfileScreen.tsx
│   ├── SettingsScreen.tsx
│   └── WorkExperienceScreen.tsx
├── components/
│   ├── PINInput.tsx
│   ├── ProfileCard.tsx
│   └── AlertBox.tsx
├── hooks/
│   ├── useAuth.ts
│   └── useProfile.ts
├── store/
│   ├── authSlice.ts
│   └── profileSlice.ts
└── utils/
    └── dateFormatter.ts

Files grouped by kind. Type-first. Most React Native tutorials lay things out this way, and there are good reasons for it. New contributors recognise the shape instantly. A reviewer skimming a take-home test can spot screens/, hooks/, components/ without thinking. The folder names map onto the framework's vocabulary, so the mental model carries from one project to the next. For three or four screens, that's enough structure to keep things in order. If you've ever done a take-home tech test, your folder structure is one of the first things a reviewer looks at, and type-first is the safe pick there.

The shape holds while the app is small. Then you add authentication with PIN setup, email verification, password recovery. You add profile management with picture uploads, account editing, password changes. Suddenly screens/ has 25 files, and finding the hook that belongs to the profile picture upload means scanning an alphabetical list of every hook in the app.

Now try to delete a feature. Remove the screen from screens/. Find its hook in hooks/. Its service in services/. Its store slice. Its components. Its validation schema. Its tests, sitting in a separate __tests__/ tree. Miss one file and you've got dead code that'll sit there for months.

That's the test. If removing a feature takes longer than building one, the structure is working against you.

One folder per feature

My app has 13 features. Each lives in a single directory:

src/features/
├── Auth/           # 85 files. Login, registration, PIN, lockout
├── Profile/        # API, store, picture upload, 5 screens
├── Settings/       # Theme, language, 3 screens
├── Education/      # Store, API, 1 screen
├── WorkExperience/ # Store, API, 4 screens
├── Home/           # 1 screen, 1 export
├── Legal/          # Privacy policy, T&Cs
├── Permissions/    # Camera, photo library, denial screens
├── MockStatus/     # Dev-only MSW status screen
├── PDF/            # PDF viewer
├── Placeholder/    # Chat, booking placeholders
├── WebView/        # Generic webview screen
└── Splash/         # Splash screen

Everything else sits outside features: shared/ for reusable components and hooks, store/ for the Redux config, navigation/, httpClients/, utils/, i18n/.

The simplest feature is two files. The most complex is 85. Each one only has the folders it actually needs. No empty services/ directory because a template said it should be there.

What 85 files look like when they're co-located

src/features/Auth/
├── __tests__/
├── api/
│   └── __tests__/
├── components/
│   ├── __tests__/
│   ├── PINDot.tsx
│   ├── PINDot.stories.tsx
│   ├── PINInput.tsx
│   ├── PINInput.stories.tsx
│   ├── PINKeypad.tsx
│   └── PINKeypad.stories.tsx
├── context/
│   └── AuthContext.tsx
├── hooks/
│   └── useAuth.ts
├── services/
│   └── pinLockoutService.ts
├── store/
│   ├── __tests__/
│   ├── actions.ts
│   ├── index.ts
│   ├── reducer.ts
│   └── selectors.ts
├── utils/
│   ├── __tests__/
│   ├── emailResendRateLimiter.ts
│   ├── pinHashing.ts
│   ├── pinValidation.ts
│   └── rateLimiter.ts
├── validation/
│   ├── __tests__/
│   ├── customRules.ts
│   ├── loginSchema.ts
│   ├── passwordRecoverySchema.ts
│   └── registrationSchema.ts
├── EmailVerificationScreen.tsx
├── ForgotPasswordScreen.tsx
├── LoginScreen.tsx
├── PINSetupScreen.tsx
├── RegistrationScreen.tsx
├── ResetPasswordScreen.tsx
└── index.ts

PIN hashing sits next to PIN validation, next to the PIN components, next to the PIN setup screen. The relationship between files is visible in the folder layout. I open Auth/ and I can see every piece of the authentication system without going anywhere else.

In a type-first structure, those same PIN files would be in components/, utils/, services/, and screens/. Four folders for one concept.

The delete test in practice

The acid test from earlier. What does it actually look like for each layout?

Type-first: delete files from screens/, components/, hooks/, services/, store/, utils/, validation/, and __tests__/. Miss a file and you've got an orphan. Miss an import and the app crashes at boot.

Feature-first: delete src/features/Auth/, remove authReducer from the store config, remove the navigation routes. Three steps. The compiler tells me if I missed a reference.

I've done this. Removing a feature that touched 40+ files took less than a minute. Most of that minute was the navigation config.

The contract that makes refactoring safe

Every feature exports only what the rest of the app needs. The index.ts at the feature root is the contract:

// src/features/Auth/index.ts
export { authReducer, login, logout, selectIsAuthenticated } from './store';
export { AuthProvider } from './context';
export { useAuth } from './hooks';
export { LoginScreen } from './LoginScreen';
export { RegistrationScreen } from './RegistrationScreen';

PIN hashing, rate limiting, lockout logic. None of that is exported. It's private to Auth. I can rewrite the entire PIN implementation, and as long as the exports don't change, nothing outside Auth notices.

The store config imports authReducer. Navigation imports the screens. That's it. The 80+ internal files are invisible to the rest of the codebase.

Features never import from other features

This is the rule that holds everything together.

If Auth needs to know whether a profile is loaded, it reads from the Redux store via a selector. It doesn't import from @app/features/Profile directly. The store is the only communication layer between features.

📊 Diagram: view it on warrendeleon.com

Each feature owns its Redux slice. The root store combines them:

import { authReducer } from '@app/features/Auth';
import { profileReducer } from '@app/features/Profile';
import { settingsReducer } from '@app/features/Settings';
import { educationReducer } from '@app/features/Education';
import { workExperienceReducer } from '@app/features/WorkExperience';

const rootReducer = combineReducers({
  settings: settingsReducer,
  auth: persistedAuthReducer,
  profile: profileReducer,
  workExperience: workExperienceReducer,
  education: educationReducer,
});

Break the no-cross-import rule once and you'll end up with circular dependencies within a week. Feature A imports from Feature B, which imports from Feature C, which imports from Feature A. The bundler throws a cryptic error and nobody knows where the cycle starts.

Shared code earns its place

If a component is used by one feature, it stays in that feature. If two or more features need it, it moves to src/shared/. The bar is high.

Every shared abstraction is a coupling point. The moment AlertBox lives in shared/, five features depend on its interface. Changing it means checking all five. I'd rather duplicate three lines in two features than create a shared utility that makes both harder to change on their own.

The hooks that end up in shared/ are the genuinely cross-cutting ones: useAppColorScheme, useHapticFeedback, useReducedMotion, useCameraPermission, usePhotoLibraryPermission. Things any screen might need. Not things that two screens happen to need right now.

Tests follow the same rule

Tests live next to the code they test. Auth store tests are in Auth/store/__tests__/. Auth validation tests are in Auth/validation/__tests__/. No separate test tree at the project root.

The one exception: cross-feature integration tests. Login flowing into profile loading. Settings changes propagating to the UI. Background tasks running across features. These span multiple features, so they sit in src/features/__tests__/, outside any single feature.

src/features/__tests__/
├── BackgroundTasks.integration.rntl.tsx
├── CrossFeatureIntegration.rntl.tsx
├── OnboardingJourney.integration.rntl.tsx
├── ProfileCompletionJourney.integration.rntl.tsx
└── RealtimeSubscription.integration.rntl.tsx

When a test breaks, the location tells me where to look. If it's in Auth/store/__tests__/, the problem is in the auth store. If it's in features/__tests__/, the problem is in how features interact. The location is the diagnosis.

When to switch

If your app has three screens and no state management, don't do this. A flat list of screens and a couple of shared hooks is fine. Feature-first adds overhead that small projects don't need.

The crossover sits around five features with their own state. Below that, the structure costs more than it saves. Above that, type-first becomes the thing slowing you down.

Open your screens/ folder right now. Count the files. If you can't tell which ones belong together just by looking at the list, the structure has already stopped helping you.

Setting it up

The structure above is a convention, not a tool. Two pieces of config make it stick.

Path aliases. Without them, you end up with import { authReducer } from '../../../features/Auth' everywhere. Add aliases in tsconfig.json:

{
  "compilerOptions": {
    "baseUrl": ".",
    "paths": {
      "@app": ["src"],
      "@app/*": ["src/*"]
    }
  }
}

And in babel.config.js so the runtime resolves them:

module.exports = {
  presets: ['@react-native/babel-preset'],
  plugins: [
    [
      'module-resolver',
      {
        root: ['./src'],
        alias: {
          '@app': './src',
        },
      },
    ],
  ],
};

yarn add -D babel-plugin-module-resolver

Now import { authReducer } from '@app/features/Auth' resolves at compile time and runtime, regardless of where the importing file sits.

An ESLint rule to keep the boundary honest. Path aliases alone won't stop someone from writing import { profileSelector } from '@app/features/Profile' inside Auth. Once that ships, the structure starts collapsing. A no-restricted-imports rule pins the boundary:

// eslint.config.mjs
export default [
  {
    rules: {
      'no-restricted-imports': ['error', {
        patterns: [
          {
            group: ['@app/features/*/*', '@app/features/*/*/**'],
            message: 'Import another feature through its public index (@app/features/X), not its internals. Within a feature, use relative imports.',
          },
        ],
      }],
    },
  },
  {
    // Tests can reach into a feature's internals to set up state.
    files: ['**/__tests__/**'],
    rules: { 'no-restricted-imports': 'off' },
  },
];

The first pattern blocks anything one level inside a feature (@app/features/Auth/store), the second anything deeper; the bare @app/features/Auth index import matches neither, so the public surface stays open. One trap worth knowing: these patterns use gitignore-style matching, not extglob, so a tempting !(index) exclusion silently matches nothing. Within a feature you use relative imports (./store, ../components), which never match the alias pattern, so a feature can always reach its own code. The one exemption is tests, which often need to reach inside a feature to set up state.

That's it. Path aliases, one ESLint rule, and the discipline to keep each feature's internals private. The architecture survives because the tooling enforces what the convention asks for.

The full project source is at github.com/warrendeleon/rn-warrendeleon.

And if you want the one-line version of this whole post: open your screens/ folder, count the files, and ask how long deleting one feature would take you today.

Detox + Cucumber BDD for React Native E2E testing

Warren de Leon — Mon, 18 May 2026 07:30:22 +0000

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

By the end of this post you'll have Detox driving an iOS simulator and an Android emulator, with Cucumber feature files written in plain English sitting on top. Five steps: install Detox, wire up Cucumber, write the support layer, write a feature, run it.

A quick word on the pairing

Detox + Cucumber isn't the default React Native E2E stack. Most teams stay imperative with Jest as the runner, or reach for WebdriverIO / Maestro when they want flow-style tests. Those are reasonable choices. Maestro especially is lovely if all you want is to record a flow.

So why add a BDD layer on top of Detox?

Because once feature files exist, QA and the PMs can read them. They can ask for scenarios you'd never think to write. Imperative Detox keeps test design inside engineering. Cucumber moves it outside.

The cost is two more dependencies and a support layer. The cost is small, in my experience, once the step definitions stabilise. New scenarios become a five-minute job.

Why BDD for E2E tests

Most Detox examples show imperative test code:

await element(by.id('email-input')).typeText('user@example.com');
await element(by.id('password-input')).typeText('password123');
await element(by.id('login-button')).tap();
await expect(element(by.id('home-screen'))).toBeVisible();

This works. It reads like code, not like a test specification. When a PM asks "what does the login test actually cover?", you point them at a TypeScript file.

Cucumber lets you write the same test in Gherkin:

Feature: User Authentication

  Scenario: Successful login
    Given the app is launched
    And I am on the "Login" screen
    When I type "user@example.com" into the input with testID "email-input"
    And I type "password123" into the input with testID "password-input"
    And I tap the "Login" button
    Then I should see the "Home" screen

Same Detox commands underneath. Anyone on the team can now read the test, review it, and suggest the scenarios you've missed. When one fails, the line that broke is in plain language, not in TypeScript.

Assumptions

This walkthrough is written against:

React Native 0.74+ (bare workflow, not Expo)
TypeScript with the standard RN Babel config
macOS host (iOS simulator and Android emulator)
Xcode 16+ with Command Line Tools, plus an iOS simulator created (e.g. iPhone 16)
Android Studio with at least one AVD created (e.g. Pixel 7 API 35)
Node 18 or later

I built this on Detox 20, @cucumber/cucumber 12, ts-node, and a recent React Native. The pieces most likely to drift are the Detox init signature and the Cucumber config keys, so I've noted both inline.

If you're on Expo, Detox needs a custom dev client. The Cucumber layer is the same regardless.

Step 1. Install Detox and Cucumber

Detox, Cucumber, and the TypeScript loader as dev dependencies:

yarn add -D detox @cucumber/cucumber ts-node tsconfig-paths
cd ios && pod install && cd ..

The iOS pod install is needed because Detox ships native code that has to be linked into the test build.

You also need two host-level tools that aren't npm packages:

brew tap wix/brew
brew install applesimutils

applesimutils is what Detox uses to drive the iOS simulator. For Android, you need a working emulator. Detox's CLI is invoked via npx detox, so no global install is needed.

Step 2. The three config files

Three files wire everything together: .detoxrc.js (or detox.config.js. Detox accepts both), cucumber.js, and a slim tsconfig.cucumber.json. The Cucumber config must be named cucumber.js (or .cjs/.mjs/.json): that's the filename cucumber-js loads by default, and nothing in this setup passes an explicit --config.

.detoxrc.js

The Detox configuration defines your app builds and device targets:

One thing .detoxrc.js does NOT do here: connect Detox to Cucumber. When Cucumber is the runner, you invoke cucumber-js directly and Detox's own testRunner config is never consulted; the support file in step 3 is the only bridge. .detoxrc.js just describes apps and devices:

module.exports = {
  apps: {
    'ios.debug': {
      type: 'ios.app',
      binaryPath: 'ios/build/Build/Products/Debug-iphonesimulator/YourApp.app',
      build: 'xcodebuild -workspace ios/YourApp.xcworkspace -scheme YourApp -configuration Debug -sdk iphonesimulator -derivedDataPath ios/build',
    },
    'android.debug': {
      type: 'android.apk',
      binaryPath: 'android/app/build/outputs/apk/debug/app-debug.apk',
      build: 'cd android && ./gradlew assembleDebug assembleAndroidTest -DtestBuildType=debug',
    },
  },
  devices: {
    simulator: {
      type: 'ios.simulator',
      device: { type: 'iPhone 16' },
    },
    emulator: {
      type: 'android.emulator',
      device: { avdName: 'Pixel_7_API_35' },
    },
  },
  configurations: {
    'ios.sim.debug': {
      device: 'simulator',
      app: 'ios.debug',
    },
    'android.emu.debug': {
      device: 'emulator',
      app: 'android.debug',
    },
  },
};

cucumber.js

The Cucumber configuration says where feature files live, where step definitions live, and how to format output:

require('ts-node').register({
  transpileOnly: true,
  compilerOptions: { module: 'commonjs', jsx: 'react' },
});

module.exports = {
  default: {
    paths: ['src/features/**/__tests__/*.feature', 'e2e/**/*.feature'],
    require: [
      'src/test-utils/cucumber/support/**/*.ts',
      'src/test-utils/cucumber/step-definitions/**/*.{ts,tsx}',
      'src/**/__tests__/**/*.cucumber.{ts,tsx}',
    ],
    format: ['./src/test-utils/cucumber/formatters/CheckmarkFormatter.js'],
    formatOptions: { colorsEnabled: true },
    strict: true,
    parallel: 2,
    retry: 1,
  },
};

Registering ts-node at the top of the config file (rather than via requireModule) is the path of least resistance with current Cucumber. It also lets you keep the compiler options local.

Option	What it does
`paths`	Where Gherkin feature files live
`require`	Where step definitions and support files live
`format`	Custom formatter for readable output
`strict`	Fails on undefined or pending steps
`parallel`	Number of parallel workers
`retry`	Retries for flaky tests in parallel mode

tsconfig.cucumber.json

A slim TypeScript config for the Cucumber runtime, separate from the main app tsconfig:

{
  "compilerOptions": {
    "module": "commonjs",
    "target": "ES2020",
    "lib": ["ES2020"],
    "moduleResolution": "node",
    "jsx": "react",
    "esModuleInterop": true,
    "skipLibCheck": true,
    "isolatedModules": true,
    "strict": false,
    "baseUrl": ".",
    "paths": { "@app/*": ["src/*"] },
    "types": ["node", "detox"]
  },
  "include": ["src/**/*.ts", "src/**/*.tsx"]
}

Two things to flag. "types": ["node", "detox"] is what teaches TypeScript that device, element, by, and waitFor are global. Without it, every step definition lights up red on device.launchApp. "strict": false is a pragmatic choice for test files (you'll thank yourself when wrestling with optional chains in scenario results).

Point cucumber-js at this config via TS_NODE_PROJECT=tsconfig.cucumber.json in the npm script.

Step 3. The support layer

Three files set up the Detox lifecycle inside Cucumber: detox-setup.ts, hooks.ts, and world.ts.

detox-setup.ts

Detox 20 exposes its programmatic lifecycle through the detox/internals entry point. The public 'detox' import gives you device, element, by, waitFor. The lifecycle hooks (init, cleanup, onTestStart, onTestDone) sit under 'detox/internals':

import detox from 'detox/internals';

export const setupDetox = async (workerId: string = '0') => {
  const config = process.env.DETOX_CONFIGURATION;
  if (!config) {
    throw new Error('DETOX_CONFIGURATION is not set (e.g. ios.sim.debug)');
  }
  await detox.init({ workerId: `cucumber-worker-${workerId}` });
};

export const cleanupDetox = async () => {
  await detox.cleanup();
};

export { detox };

hooks.ts

The glue between Cucumber's lifecycle and Detox's device management:

import { After, AfterAll, Before, BeforeAll, Status } from '@cucumber/cucumber';
import { device } from 'detox';

import { cleanupDetox, detox, setupDetox } from './detox-setup';
import { DetoxWorld } from './world';

BeforeAll({ timeout: 180 * 1000 }, async function () {
  const workerId = process.env.CUCUMBER_WORKER_ID ?? '0';
  await setupDetox(workerId);
  await device.launchApp({
    newInstance: true,
    launchArgs: { detoxEnableSynchronization: 0 },
  });
  await device.enableSynchronization();
});

Before({ timeout: 30000 }, async function (this: DetoxWorld, { pickle }) {
  await detox.onTestStart({
    title: pickle.name,
    fullName: pickle.name,
    status: 'running',
  });
  await device.reloadReactNative();
});

After(async function (this: DetoxWorld, { pickle, result }) {
  const testStatus = result?.status === Status.PASSED ? 'passed' : 'failed';
  if (result?.status === Status.FAILED) {
    try {
      await device.takeScreenshot(pickle.name);
    } catch (error) {
      console.error('Failed to take screenshot:', error);
    }
  }
  await detox.onTestDone({
    title: pickle.name,
    fullName: pickle.name,
    status: testStatus,
  });
});

AfterAll(async function () {
  await cleanupDetox();
});

Hook	Timeout	What it does
`BeforeAll`	180s	Boots the simulator, launches the app
`Before`	30s	Reloads React Native for a fresh state per scenario
`After`	default	Takes a screenshot on failure, notifies Detox
`AfterAll`	default	Tears down Detox

The synchronisation sequence matters. Launch with synchronisation disabled (detoxEnableSynchronization: 0), then re-enable it after the app is running. This sidesteps the Detox timeout you hit when the initial bundle load is slow.

world.ts

A custom Cucumber World that carries Detox context between steps:

import { IWorldOptions, setWorldConstructor, World } from '@cucumber/cucumber';
import { device } from 'detox';

export class DetoxWorld extends World {
  device: typeof device;
  testID: string | null;

  constructor(options: IWorldOptions) {
    super(options);
    this.device = device;
    this.testID = null;
  }

  setTestID(id: string) { this.testID = id; }
  getTestID(): string {
    if (!this.testID) throw new Error('No testID set');
    return this.testID;
  }
}

setWorldConstructor(DetoxWorld);

Calling setWorldConstructor is what wires this class into every this inside a step. Forget that call and this.device is undefined.

Step 4. Writing your first feature file

Feature files are plain text with Gherkin syntax. Each scenario describes a user flow. Drop a file at src/features/Auth/__tests__/Login.feature:

Feature: User Authentication

  Scenario: Successful login
    Given the app is launched
    And I am on the "Login" screen
    When I type "testuser@example.com" into the input with testID "email-input"
    And I type "SecurePass123" into the input with testID "password-input"
    And I tap the "Login" button
    Then I should see the "Home" screen

  Scenario: Login with invalid credentials
    Given the app is launched
    And I am on the "Login" screen
    When I type "testuser@example.com" into the input with testID "email-input"
    And I type "WrongPassword" into the input with testID "password-input"
    And I tap the "Login" button
    Then I should see text "Invalid email or password"

  Scenario: Deep link opens password reset
    Given the app is launched via password reset deep link
    Then I should see the "Reset Password" screen

Tags let you filter which scenarios to run:

@accessibility @voiceover @ios
Feature: VoiceOver Gestures

  @eaa
  Scenario: Navigate login form with swipe gestures
    ...

Then in your test command:

yarn detox:ios:test --tags "@accessibility and @ios"

Step 5. Writing step definitions

Each Gherkin step maps to a function. The step definitions are the bits you'll reuse across every feature file once they exist.

A note on Detox globals before we go further: device, element, by, and waitFor exist at compile time because step 2's tsconfig.cucumber.json declared them ("types": ["detox", "node"]). Skip that and every step definition shows red squigglies on device.launchApp.

Common steps

import { Given, When, Then } from '@cucumber/cucumber';

Given('the app is launched', async function () {
  await device.terminateApp();
  await device.clearKeychain(); // iOS only: a silent no-op on Android
  await device.launchApp({ newInstance: true });
  await new Promise(r => setTimeout(r, 500));
});

Given('I am on the {string} screen', async function (screen: string) {
  const testID = `${screen.toLowerCase().replace(/\s+/g, '-')}-screen`;
  await waitFor(element(by.id(testID)))
    .toBeVisible()
    .withTimeout(20000);
});

When('I tap the {string} button', async function (name: string) {
  const testID = `${name.toLowerCase().replace(/\s+/g, '-')}-button`;
  await element(by.id(testID)).tap();
});

When('I type {string} into the input with testID {string}',
  async function (text: string, testID: string) {
    await waitFor(element(by.id(testID)))
      .toBeVisible()
      .withTimeout(5000);
    await element(by.id(testID)).replaceText(text);
  }
);

Then('I should see the {string} screen', async function (screen: string) {
  const testID = `${screen.toLowerCase().replace(/\s+/g, '-')}-screen`;
  await new Promise(r => setTimeout(r, 500));
  await waitFor(element(by.id(testID)))
    .toBeVisible()
    .withTimeout(20000);
});

Then('I should see text {string}', async function (text: string) {
  await waitFor(element(by.text(text)))
    .toBeVisible()
    .withTimeout(5000);
});

Three patterns to lock in here. First, a consistent testID convention: screen names become kebab-case with a -screen or -button suffix. "Login" maps to login-screen, "Home" to home-screen, "Submit" to submit-button. Second, every assertion goes through waitFor with a timeout, not raw expect. Animations and network calls need settling time and expect doesn't give it to them. Third, replaceText over typeText. typeText appends to whatever's already there. replaceText clears first. For form inputs you want the second.

Save the file as src/test-utils/cucumber/step-definitions/common.cucumber.tsx and Cucumber picks it up via the glob in your cucumber.js.

Element finding strategies

Sometimes by.id() isn't enough. A step definition that doesn't break across iOS and Android tries multiple strategies:

When('I tap the text {string}', async function (text: string) {
  try {
    await element(by.text(text)).tap();
  } catch {
    try {
      await element(by.label(text)).tap();
    } catch {
      const testID = text.toLowerCase().replace(/\s+/g, '-');
      await element(by.id(testID)).tap();
    }
  }
});

Try by.text() first (visible text), fall back to by.label() (accessibility label), then by.id() (testID). This handles buttons that render text differently across platforms.

What the app talks to during these tests

The scenarios above type credentials and expect a Home screen, which raises the question every E2E setup has to answer: what backend is the app hitting? Run it against a real one and your suite fails whenever staging hiccups. The deterministic answer is to mock at the bundle level with an E2E build flag, which is its own post: Metro runtime mocking for deterministic React Native E2E tests. Until you have that layer, point the E2E build at a stable test environment and treat network flakes as suite failures, not test failures.

A custom formatter

Cucumber's default output is noisy. A custom formatter gives you clean results that are easier to read in CI logs:

✓ Feature: User Authentication
  ✓ Scenario: Successful login (2340ms)
    ✓ Given the app is launched (890ms)
    ✓ And I am on the "Login" screen (450ms)
    ✓ When I type "testuser@example.com" into the input with testID "email-input" (120ms)
    ✓ And I type "SecurePass123" into the input with testID "password-input" (95ms)
    ✓ And I tap the "Login" button (85ms)
    ✓ Then I should see the "Home" screen (700ms)

  ✗ Scenario: Login with expired token (1890ms)
    ✓ Given the app is launched (850ms)
    ✓ And I am on the "Login" screen (420ms)
    ✗ Then I should see the "Session Expired" screen (620ms)
      Error: Element not found: session-expired-screen

2 scenarios (1 passed, 1 failed)
12 steps (11 passed, 1 failed)

The formatter is a small class that subscribes to Cucumber's envelope events (testStepFinished, testCaseFinished), maps each step's status to an icon and colour, and prints the line. About 80 lines all in.

The full version in my repo tracks pickles, maps test steps back to their Gherkin text, times each step, and prints a summary with pass and fail counts. The sketch above is the shape; the full file is src/test-utils/cucumber/formatters/CheckmarkFormatter.js in the repo linked at the end.

Parallel execution

Detox can run scenarios across multiple simulators. Cucumber's parallel setting drives the worker count, and each worker gets its own Detox instance.

# Run with 3 parallel simulators
DETOX_WORKERS=3 yarn detox:ios:test:parallel

The BeforeAll hook reads CUCUMBER_WORKER_ID and passes it to setupDetox so each worker initialises against its own simulator. Cucumber distributes scenarios across workers for you.

Setting	Local	CI
iOS workers	2-3	3
Android workers	1-2	2
Retry on failure	1	1
Fail fast	No	No

One tip on parallel runs. Keep fail-fast off when running in parallel. One flaky scenario shouldn't kill the other workers, and with retry enabled the flake gets a second chance while the rest keep going. On a single-worker run, fail-fast on is fine.

Accessibility testing with BDD

Detox doesn't drive VoiceOver or TalkBack directly. Manual screen reader testing still has a job to do. What Detox can check is whether the right accessibility labels, roles, and traits are set on every element. Written as Gherkin scenarios, those checks catch a class of regression that nobody is going to notice manually until a user with VoiceOver opens the app.

My repo has two feature files for this, one for iOS patterns and one for Android.

@accessibility @voiceover @ios @eaa
Feature: VoiceOver Gestures

  Scenario: Navigate login form with swipe right
    Given the app is launched
    And I am on the "Login" screen
    And VoiceOver focus is on the "Email" element
    When I swipe right to move to the next element
    Then VoiceOver focus should move to the next element
    And I should hear the accessibility label for "Password"

  Scenario: Activate login button with double tap
    Given the app is launched
    And I am on the "Login" screen
    And I have entered valid credentials
    And VoiceOver focus is on the "Login" button
    When I double tap to activate
    Then I should see the "Home" screen

  Scenario: Error announced via live region
    Given the app is launched
    And I am on the "Login" screen
    And I have entered invalid credentials
    When I double tap to activate
    Then the error message should be announced via a live region

The step definitions for accessibility testing maintain state:

interface AccessibilityState {
  focusedElementIndex: number;
  visitedElements: string[];
  lastAnnouncement: string | null;
  granularity: 'characters' | 'words' | 'lines' | 'headings' | 'default';
}

This tracks expected focus order, announcement text, and reading granularity. Around 50 scenarios across the two feature files cover labels, focus behaviour, live region announcements, and custom actions. They don't replace a manual pass with a real screen reader. They do stop the obvious regressions from shipping.

Run it

The scripts I use sit in package.json like this:

{
  "scripts": {
    "detox:ios:build": "detox build -c ios.sim.debug",
    "detox:ios:test": "DETOX_CONFIGURATION=ios.sim.debug TS_NODE_PROJECT=tsconfig.cucumber.json cucumber-js",
    "detox:ios:test:parallel": "yarn detox:ios:test --parallel ${DETOX_WORKERS:-2} --retry 1",
    "e2e:ios": "yarn detox:ios:build && yarn detox:ios:test"
  }
}

Note the test script runs cucumber-js directly rather than detox test. With Cucumber as the runner, you don't go through Detox's runner wrapper. Detox is initialised from your support file.

First run:

yarn e2e:ios

$ detox build -c ios.sim.debug
Building app for ios.sim.debug...
xcodebuild ... ** BUILD SUCCEEDED **

$ cucumber-js
✓ Feature: User Authentication
  ✓ Scenario: Successful login (2340ms)
  ✓ Scenario: Login with invalid credentials (1820ms)

2 scenarios (2 passed)
12 steps (12 passed)

If xcodebuild fails on the first run, check that the simulator named in .detoxrc.js actually exists (xcrun simctl list devices). The most common first-run trip is a hard-coded iPhone 16 that you never created in Xcode.

Common pitfalls

Synchronisation is the hardest part. Detox tries to wait for the app to be idle automatically, but animations, timers, and network calls can confuse it. The launch-with-sync-disabled pattern (detoxEnableSynchronization: 0 then enableSynchronization() after) sidesteps the most common timeout.

typeText appends, replaceText replaces. If a field has placeholder text or previous input, typeText adds to it. Use replaceText for form inputs where you want a clean value.

Screenshots on failure. The After hook captures a screenshot when a scenario fails. Without this, debugging CI failures is squinting at logs. Name the screenshot after the scenario so you can match a failure to its image.

Describe behaviour, not implementation. Write "When I log in", not "When I type into email-input and tap login-button". The implementation details belong in step definitions, not in the Gherkin. If a non-engineer can't read the feature file aloud and understand it, you've leaked detail into the wrong layer.

The full file structure

src/
  test-utils/
    cucumber/
      formatters/
        CheckmarkFormatter.js    # Custom ✓/✗ formatter
      step-definitions/
        common.cucumber.tsx      # Shared steps (tap, type, navigate)
        auth.cucumber.tsx         # Authentication steps
        accessibility.cucumber.tsx # VoiceOver + TalkBack steps
      support/
        detox-setup.ts           # Detox initialisation
        hooks.ts                  # BeforeAll/Before/After/AfterAll
        world.ts                  # Cucumber World context
e2e/
  accessibility/
    VoiceOverGestures.feature    # iOS screen reader tests
    TalkBackGestures.feature     # Android screen reader tests

What you get

The setup is a morning's work. The first feature file is an afternoon. After that, adding scenarios is fast because the step definitions are reusable across features.

What you've built by the end:

Tests that anyone on the team can read. Product, QA, designers. The Gherkin file is the spec and the test in one place, and when a scenario fails, the report names the step that broke rather than a line of test code.
Parallel execution that works with Detox. Three simulators, three workers, three times faster on CI.
Accessibility regression coverage. Around 50 scenarios verifying labels, roles, and traits. Not a swap for manual screen reader testing, but a net that stops the obvious regressions from reaching QA.

This post covers E2E testing. For unit and integration tests I use MSW v2 to mock the network layer instead of jest.fn(). The two pair well: MSW for fast, focused tests against real HTTP calls; Detox + Cucumber for full user flows on a real device.

The code in this post is from rn-warrendeleon, my personal React Native project. The full Detox + Cucumber setup, step definitions, custom formatter, and accessibility feature files all live there.