DEV Community: Warren de Leon

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, 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 — and 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, the QA folks 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 dance 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.

React Native token storage: AsyncStorage vs SecureStore

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

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

Where one storage layer runs out of road

Most React Native apps put everything in AsyncStorage. Tokens, user data, preferences, session state. All in one place, all in plain text.

AsyncStorage is a key-value store, backed by SQLite on Android and on-disk files on iOS. It's fast and convenient. It's also unencrypted. Anyone with physical access, or a rooted/jailbroken device, can read every value.

For a theme preference, that's fine. For an access token, it's an incident.

This post walks through the three tiers I use in production: hardware-backed Keychain for tokens, an encrypted store for PII, and AsyncStorage (via Redux Persist) for preferences. Each tier is one short wrapper. The work is in deciding what lives where, then keeping that boundary honest in your auth flow.

📊 Diagram: view it on warrendeleon.com

Assumptions

The setup below was written against:

React Native 0.74+ (bare workflow, not Expo)
TypeScript with the standard RN Babel config
Redux Toolkit + Redux Persist for state management
iOS 13+ and Android API 23+ (hardware-backed Keystore needs API 23 as a floor)
A Supabase backend (or any REST API that returns access/refresh tokens)

On Expo, swap react-native-keychain for expo-secure-store in the Tier 1 wrapper. The structure stays the same.

The three tiers

Tier	Library	Security	Speed	Use for
1. SecureStore	react-native-keychain	Hardware-backed (Keychain/Keystore)	Slowest	Tokens, encryption keys, PINs
2. EncryptedStore	react-native-encrypted-storage	AES-256 encryption	Medium	PII (email, name, phone)
3. AsyncStorage	@react-native-async-storage	None (plain text)	Fastest	Preferences (theme, language)

Each tier is a thin wrapper around a library. The wrapper enforces typed keys (so you can't store a token in the wrong tier) and provides a consistent API.

Tier 1: SecureStore (Keychain / Keystore)

The top tier. Uses the platform's hardware-backed secure enclave: iOS Keychain or Android Keystore. Data is encrypted by the OS itself and can require biometric authentication to read.

yarn add react-native-keychain
cd ios && pod install && cd ..

react-native-keychain is a native module, so iOS needs a pod install. On Android, set minSdkVersion = 23 (or higher) in android/build.gradle to reach the hardware-backed Keystore code path.

A caveat on Android: even on API 23+, whether keys actually sit on a Trusted Execution Environment or a StrongBox depends on the device and OEM. Some modern handsets still report software-only storage. If your threat model needs a guarantee, call Keychain.getSecurityLevel() at runtime and gate the sensitive operations on the result. iOS Keychain is hardware-backed on every supported device.

The wrapper:

// src/utils/storage/SecureStore.ts
import * as Keychain from 'react-native-keychain';

export enum SecureStoreKey {
  ACCESS_TOKEN = 'accessToken',
  REFRESH_TOKEN = 'refreshToken',
  USER_ID = 'userId',
  HASHED_PIN = 'hashedPIN',
  ENCRYPTION_KEY = 'encryptionKey',
}

const SERVICE_PREFIX = 'com.warrendeleon.portfolio';

// Keys the user should re-authenticate to read. Tokens stay un-gated so the
// refresh interceptor and cold-start session check never trigger a prompt.
const BIOMETRIC_GATED: SecureStoreKey[] = [
  SecureStoreKey.HASHED_PIN,
  SecureStoreKey.ENCRYPTION_KEY,
];

export const SecureStore = {
  async set(key: SecureStoreKey, value: string): Promise<boolean> {
    await Keychain.setGenericPassword(key, value, {
      service: `${SERVICE_PREFIX}.${key}`,
      ...(BIOMETRIC_GATED.includes(key) && {
        accessControl: Keychain.ACCESS_CONTROL.BIOMETRY_ANY_OR_DEVICE_PASSCODE,
      }),
      accessible: Keychain.ACCESSIBLE.WHEN_UNLOCKED_THIS_DEVICE_ONLY,
    });
    return true;
  },

  async get(key: SecureStoreKey): Promise<string | null> {
    const result = await Keychain.getGenericPassword({
      service: `${SERVICE_PREFIX}.${key}`,
    });
    return result ? result.password : null;
  },

  async remove(key: SecureStoreKey): Promise<boolean> {
    await Keychain.resetGenericPassword({
      service: `${SERVICE_PREFIX}.${key}`,
    });
    return true;
  },

  async clear(): Promise<boolean> {
    for (const key of Object.values(SecureStoreKey)) {
      await Keychain.resetGenericPassword({
        service: `${SERVICE_PREFIX}.${key}`,
      });
    }
    return true;
  },
};

Four decisions in that wrapper are worth flagging:

One service per key. Keychain stores a single credential per service identifier. Using com.warrendeleon.portfolio.accessToken and com.warrendeleon.portfolio.refreshToken as separate services keeps them from overwriting each other.
Biometric gating is per key, not blanket. BIOMETRY_ANY_OR_DEVICE_PASSCODE means reading the value can surface a Face ID / Touch ID / passcode prompt, at whatever moment the read happens. Gate the keys a human should consciously unlock (the hashed PIN, the encryption key) and leave the tokens un-gated, or your background token refresh and cold-start session check will prompt the user at times that look like bugs.
This device only. WHEN_UNLOCKED_THIS_DEVICE_ONLY keeps the data off iCloud Keychain backups. Tokens shouldn't roam.
Typed enum keys. You can't accidentally pass a string. The compiler enforces that only token-level data goes into SecureStore.

Tier 2: EncryptedStore (AES-256)

The middle tier. Data is encrypted with AES-256, no hardware-backed gate, no biometric prompt. Faster than Keychain, much safer than plain text.

yarn add react-native-encrypted-storage
cd ios && pod install && cd ..

The wrapper:

// src/utils/storage/EncryptedStore.ts
import EncryptedStorage from 'react-native-encrypted-storage';

export enum EncryptedStoreKey {
  USER_EMAIL = 'userEmail',
  USER_FIRST_NAME = 'userFirstName',
  USER_LAST_NAME = 'userLastName',
  USER_PHONE_NUMBER = 'userPhoneNumber',
  PROFILE_PICTURE_URL = 'profilePictureURL',
  AUTH_PROVIDER = 'authProvider',
}

export const EncryptedStore = {
  async set(key: EncryptedStoreKey, value: string): Promise<boolean> {
    await EncryptedStorage.setItem(key, value);
    return true;
  },

  async get(key: EncryptedStoreKey): Promise<string | null> {
    return await EncryptedStorage.getItem(key);
  },

  async remove(key: EncryptedStoreKey): Promise<boolean> {
    await EncryptedStorage.removeItem(key);
    return true;
  },

  async setMultiple(
    items: { key: EncryptedStoreKey; value: string }[]
  ): Promise<boolean> {
    for (const item of items) {
      await EncryptedStorage.setItem(item.key, item.value);
    }
    return true;
  },

  async getMultiple(
    keys: EncryptedStoreKey[]
  ): Promise<Record<string, string | null>> {
    const result: Record<string, string | null> = {};
    for (const key of keys) {
      result[key] = await EncryptedStorage.getItem(key);
    }
    return result;
  },

  async clear(): Promise<boolean> {
    await EncryptedStorage.clear();
    return true;
  },
};

Why not put PII in SecureStore? Performance. Keychain access runs a system-level security check, and sometimes a biometric prompt. For rendering a user's name on a profile screen, that overhead isn't worth paying. EncryptedStore gives you AES-256 at rest without the hardware gate.

The batch operations (setMultiple, getMultiple) matter for auth flows that need to write a handful of fields together:

await EncryptedStore.setMultiple([
  { key: EncryptedStoreKey.USER_EMAIL, value: user.email },
  { key: EncryptedStoreKey.USER_FIRST_NAME, value: user.firstName },
  { key: EncryptedStoreKey.USER_LAST_NAME, value: user.lastName },
]);

Tier 3: AsyncStorage + Redux Persist

The fastest tier. Plain text, no encryption. Reserved for data with no security weight: theme preference, language selection.

yarn add @react-native-async-storage/async-storage redux-persist @reduxjs/toolkit react-redux
cd ios && pod install && cd ..

You don't talk to AsyncStorage directly for preferences. Redux Persist does it for you. It saves your Redux state to AsyncStorage and rehydrates it on app launch.

The persist config is where the security boundary lives:

// src/store/configureStore.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { combineReducers, configureStore } from '@reduxjs/toolkit';
import { persistReducer, persistStore, FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER } from 'redux-persist';

import { authReducer } from '@app/features/Auth';
import { settingsReducer } from '@app/features/Settings';

// Auth slice gets its own persist config so we can whitelist a single field.
const authPersistConfig = {
  key: 'auth',
  storage: AsyncStorage,
  whitelist: ['biometricEnabled'],
};

const persistedAuthReducer = persistReducer(authPersistConfig, authReducer);

const rootReducer = combineReducers({
  settings: settingsReducer,
  auth: persistedAuthReducer,
});

// Root persist config only persists the settings slice (theme, language).
const rootPersistConfig = {
  key: 'root',
  storage: AsyncStorage,
  whitelist: ['settings'],
};

const persistedReducer = persistReducer(rootPersistConfig, rootReducer);

export const store = configureStore({
  reducer: persistedReducer,
  middleware: getDefaultMiddleware =>
    getDefaultMiddleware({
      serializableCheck: {
        // Redux Persist dispatches non-serialisable actions during rehydration.
        // Ignore them so the serialisable-check middleware doesn't warn.
        ignoredActions: [FLUSH, REHYDRATE, PAUSE, PERSIST, PURGE, REGISTER],
      },
    }),
});

export const persistor = persistStore(store);

Config	What it persists	What it excludes
`rootPersistConfig`	Settings slice only (theme, language)	Everything else
`authPersistConfig`	`biometricEnabled` flag only	user, error, isLoading, tokens

The whitelist is the load-bearing part. It's a positive list: only the slices you name get persisted, everything else is ephemeral. That's how you stop tokens from finding their way into AsyncStorage through Redux.

const settingsSlice = createSlice({
  name: 'settings',
  initialState: {
    theme: 'system' as 'light' | 'dark' | 'system',
    language: 'en' as string,
  },
  reducers: {
    setTheme: (state, action) => { state.theme = action.payload; },
    setLanguage: (state, action) => { state.language = action.payload; },
  },
});

When the user changes theme or language, Redux Persist writes to AsyncStorage for you. On next launch, PersistGate waits for rehydration before rendering:

// App.tsx
import { Provider } from 'react-redux';
import { PersistGate } from 'redux-persist/integration/react';
import { persistor, store } from '@app/store/configureStore';

export default function App() {
  return (
    <Provider store={store}>
      <PersistGate loading={null} persistor={persistor}>
        {/* your screens */}
      </PersistGate>
    </Provider>
  );
}

PersistGate blocks render until the persisted slice has been loaded back into the store. Without it, the app flashes the default state for one frame before the persisted theme/language takes over.

How the tiers compose in an auth flow

The wrappers carry their weight when you watch them work together across login, session restore, logout, and token refresh.

Login

// 1. Backend returns tokens and user data
const { access_token, refresh_token, user } = await authClient.signIn(credentials);

// 2. Tokens → SecureStore (Tier 1)
await SecureStore.set(SecureStoreKey.ACCESS_TOKEN, access_token);
await SecureStore.set(SecureStoreKey.REFRESH_TOKEN, refresh_token);
await SecureStore.set(SecureStoreKey.USER_ID, user.id);

// 3. PII → EncryptedStore (Tier 2)
await EncryptedStore.set(EncryptedStoreKey.USER_EMAIL, user.email);
await EncryptedStore.set(EncryptedStoreKey.USER_FIRST_NAME, user.firstName);

// 4. Redux state updated → UI renders
dispatch(setUser(user));
// Settings (theme, language) already in Redux via Persist (Tier 3)

App startup (session restore)

export const checkSession = createAsyncThunk(
  'auth/checkSession',
  async () => {
    // Check if we have a valid token (Tier 1)
    const accessToken = await SecureStore.get(SecureStoreKey.ACCESS_TOKEN);
    if (!accessToken) return null;

    // Restore user data (Tier 2)
    const email = await EncryptedStore.get(EncryptedStoreKey.USER_EMAIL);
    const firstName = await EncryptedStore.get(EncryptedStoreKey.USER_FIRST_NAME);
    const userId = await SecureStore.get(SecureStoreKey.USER_ID);

    // Settings already restored by PersistGate (Tier 3)
    return { id: userId, email, firstName };
  }
);

Logout

// 1. Invalidate refresh token on backend
await authClient.logout();

// 2. Clear tokens (Tier 1)
await SecureStore.clear();

// 3. Clear PII (Tier 2)
await EncryptedStore.clear();

// 4. Clear Redux auth state
dispatch(resetAuth());

// Settings (Tier 3) persist through logout. User keeps their theme and language.

The logout sequence is deliberate. Tier 1 and Tier 2 clear because tokens and PII belong to the session. Tier 3 stays because theme and language belong to the device.

Token refresh

The Axios interceptor handles token refresh in the background. It reads from and writes to SecureStore without touching the other tiers:

import axios from 'axios';
import Config from 'react-native-config';

axiosInstance.interceptors.response.use(
  response => response,
  async error => {
    // Only retry once per request, or a refresh that keeps 401ing loops forever.
    if (error.response?.status === 401 && !error.config._retry) {
      error.config._retry = true;
      try {
        const refreshToken = await SecureStore.get(SecureStoreKey.REFRESH_TOKEN);
        // Supabase's GoTrue wants grant_type as a query parameter, and a bare
        // axios call needs the absolute URL (there is no baseURL here).
        const { data } = await axios.post(
          `${Config.SUPABASE_URL}/auth/v1/token?grant_type=refresh_token`,
          { refresh_token: refreshToken },
          { headers: { apikey: Config.SUPABASE_ANON_KEY } }
        );

        // Update tokens in SecureStore
        await SecureStore.set(SecureStoreKey.ACCESS_TOKEN, data.access_token);
        await SecureStore.set(SecureStoreKey.REFRESH_TOKEN, data.refresh_token);

        // Retry the original request
        error.config.headers.Authorization = `Bearer ${data.access_token}`;
        return axiosInstance(error.config);
      } catch (refreshError) {
        // No refresh token, or it has expired: the session is over. Clear the
        // secure tier so the app falls back to the login flow.
        await SecureStore.clear();
        return Promise.reject(refreshError);
      }
    }
    return Promise.reject(error);
  }
);

The _retry flag stops a failed refresh from looping forever, and a failed refresh clears the secure tier so the app falls back to the login flow. One case it doesn't cover: several requests hitting a 401 at once each fire their own refresh. Collapsing those into a single in-flight refresh is a separate problem.

The data classification

Every piece of stored data has a clear home:

Data	Tier	Why
Access token	1 (SecureStore)	Grants API access. Hardware-backed protection.
Refresh token	1 (SecureStore)	Can generate new access tokens. Highest value target.
User ID	1 (SecureStore)	Used to identify the user across requests.
Hashed PIN	1 (SecureStore)	Local authentication credential.
Encryption key	1 (SecureStore)	Protects Tier 2 data. Must be in hardware.
Email	2 (EncryptedStore)	PII. Encrypted but needs fast access for display.
Name	2 (EncryptedStore)	PII. Shown on profile screens.
Phone number	2 (EncryptedStore)	PII. Shown in settings.
Auth provider	2 (EncryptedStore)	Not sensitive but related to auth session.
Biometric preference	3 (AsyncStorage via Redux Persist)	A preference, not a secret. It gates UX, not access.
Theme	3 (AsyncStorage)	Non-sensitive preference. Survives logout.
Language	3 (AsyncStorage)	Non-sensitive preference. Survives logout.

The rule is short: if it grants access, Tier 1. If it identifies a person, Tier 2. If it's a preference, Tier 3. The classification shapes the project layout too. Storage wrappers sit in a shared utils/storage/ folder, and the auth flow that orchestrates them lives inside the Auth feature.

Common pitfalls

Don't forget that iOS Keychain values survive an uninstall. Delete the app, reinstall it, and Tier 1 still holds the old tokens while Tier 2 and Tier 3 came back empty. Your session check then restores a login the user thought they'd destroyed, with no profile data behind it. Detect first run (an AsyncStorage sentinel works, since AsyncStorage does get wiped) and clear SecureStore before reading anything from it.

Don't store tokens in Redux. Redux state can be serialised, logged, persisted to AsyncStorage via Redux Persist, and inspected with DevTools. Even with a blacklisted auth slice, one misconfiguration exposes tokens. Keep tokens in SecureStore, full stop.

Don't skip the typed enums. Without SecureStoreKey and EncryptedStoreKey, you're passing raw strings. One typo and you read from the wrong key. One wrong tier and you store a token in plain text. The type system is the cheapest security audit you'll ever run.

Don't forget to clear on logout. Clear SecureStore but skip EncryptedStore and the user's PII sticks around after they log out. The clear() method on each tier is the contract: call both during logout.

Don't assume Keychain is fast. SecureStore runs a round trip to the secure enclave. On older devices it can take 100-200ms per read. Don't call it in a render loop. Read tokens once at startup and pass them through your HTTP interceptor.

Use Redux Persist whitelist, not blacklist. Name what should persist. blacklist is risky because new slices persist by default. One new slice with sensitive data and you have a leak. whitelist is opt-in, and safer.

So why three libraries

One library (AsyncStorage) leaves tokens in plain text. One library (react-native-keychain) is too slow for non-sensitive reads. Three libraries, three wrappers, three enums. Each wrapper sits under 50 lines.

What you walk away with: tokens that can't be read without biometric authentication, PII that's encrypted at rest, and preferences that load on the first frame. Each piece of data is protected at the level it actually needs.

Store everything in one place and you protect nothing. Separate by sensitivity and you protect what matters.

The code examples in this post are from rn-warrendeleon, my personal React Native project. The full SecureStore, EncryptedStore, and Redux Persist configuration are all in the repo.

Setting up MSW v2 in React Native

Warren de Leon — Mon, 04 May 2026 12:37:29 +0000

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

Why MSW over manual mocks

Most React Native projects mock their API layer with jest.fn(). You mock fetch or your Axios instance, define what it returns, and test against that.

It works. Until it doesn't.

The problem: you're testing your code's interaction with a mock, not with an HTTP layer. If your API client changes how it constructs URLs, adds headers, or handles retries, the mock doesn't catch the regression. This matters even more if you're validating responses at runtime with something like Zod, because you want the validation layer to run against real response shapes, not hand-crafted mock objects. The mock always returns what you told it to return, regardless of what the code actually sent.

Mock Service Worker (MSW) intercepts requests at the network level. Your code makes real HTTP calls. MSW catches them before they leave the process and returns your mock responses. Everything between your component and the network is exercised: the Redux thunk, the Axios interceptors, the error handling, the response parsing.

Manual mocks replace your code. MSW replaces the network. The code runs exactly as it would on a device, right up to the point where the request would have left it.

📊 Diagram: view it on warrendeleon.com

Assumptions

The setup below was written against:

React Native 0.74+ with the default react-native Jest preset
TypeScript with the standard RN Babel config
Redux Toolkit (the custom render wrapper assumes this)
Node 18 or later (Node 20 recommended)

If you're on an older RN version, an Expo Jest preset, or no Redux, the concepts still apply but a few snippets will need adjustment.

Installation

MSW v2 runs in Jest tests via the Node.js server. The browser service worker isn't relevant for mobile, so ignore everything in the MSW docs about service-worker registration.

yarn add -D msw node-fetch@2 web-streams-polyfill

msw is the obvious one. node-fetch and web-streams-polyfill are the polyfills MSW v2 needs in the React Native Jest environment, which I'll wire up in the next step.

💡 Why pin node-fetch@2? node-fetch v3+ is ESM-only and won't load through require() in a CommonJS Jest setup file. Either pin to v2 (what this post does), or migrate the polyfills file to ESM. v2 is the lower-friction path on a default React Native Jest preset.

💡 Don't trust posts that say "no polyfills required". MSW v2 is built on the Fetch API and Web Streams. Some Node + Jest combinations have these globals; the React Native Jest preset doesn't. Without the polyfills you'll see ReferenceError: Response is not defined or TextEncoder is not defined the first time MSW tries to construct a response.

Polyfills

Create jest.polyfills.cjs at the project root. It must be .cjs (not .ts) because Jest loads it before the TypeScript transformer is set up:

/**
 * MSW polyfills for React Native.
 * Required for Mock Service Worker v2 in Jest tests.
 */

// TextEncoder / TextDecoder
const { TextEncoder, TextDecoder } = require('util');
global.TextEncoder = TextEncoder;
global.TextDecoder = TextDecoder;

// Fetch API
if (!global.fetch) {
  global.fetch = require('node-fetch');
  global.Headers = require('node-fetch').Headers;
  global.Request = require('node-fetch').Request;
  global.Response = require('node-fetch').Response;
}

// ReadableStream (for response streaming)
if (!global.ReadableStream) {
  try {
    const { ReadableStream } = require('web-streams-polyfill');
    global.ReadableStream = ReadableStream;
  } catch {
    // web-streams-polyfill is optional for older MSW v2
  }
}

This file runs before the test framework loads, so beforeAll, jest, etc. aren't available here. It's purely for setting up globals.

Jest config

Wire the polyfills file and a separate setup file into jest.config.cjs:

module.exports = {
  preset: 'react-native',
  testEnvironment: 'node',
  setupFiles: ['<rootDir>/jest.polyfills.cjs'],
  setupFilesAfterEnv: ['<rootDir>/jest.setup.ts'],
  transformIgnorePatterns: [
    // The default RN preset ignores most of node_modules; MSW needs to be transformed.
    'node_modules/(?!(react-native|@react-native|msw|until-async|rettime|@mswjs|@open-draft|@bundled-es-modules|headers-polyfill|strict-event-emitter|outvariant)/)',
  ],
  moduleFileExtensions: ['ts', 'tsx', 'js', 'jsx', 'json', 'node'],
};

Two keys do the work:

Key	When it runs	Use for
`setupFiles`	Before the Jest framework is installed	Polyfills, global variables, anything that doesn't need `jest`/`expect`
`setupFilesAfterEnv`	After Jest framework, before each test file	`beforeAll`/`afterEach` hooks, MSW server lifecycle, custom matchers

The transformIgnorePatterns line is the other gotcha: the default RN preset skips transforming node_modules, but MSW ships modern syntax that Jest can't run as-is. Add MSW and its untranspiled dependencies (msw|until-async|rettime|@mswjs|@open-draft|@bundled-es-modules|headers-polyfill|strict-event-emitter|outvariant) to the allow-list or you'll see SyntaxError: Cannot use import statement outside a module from inside node_modules/msw/. Newer MSW versions ship more of these; if the error names a package that isn't in your list yet, add it to the same group.

The server

Create src/test-utils/msw/server.ts:

import { setupServer } from 'msw/node';
import { handlers } from './handlers';

/**
 * MSW server for Jest. Started/stopped in jest.setup.ts.
 * Use `server.use(...errorHandlers)` to override per test.
 */
export const server = setupServer(...handlers);

The server takes your default handlers (success responses) and intercepts matching requests.

Wiring up the lifecycle

In jest.setup.ts (which Jest loads via setupFilesAfterEnv), start the server before tests, reset between tests, close after:

import '@testing-library/jest-native/extend-expect'; // RNTL >=12.4 has these matchers built in; this import is only for older RNTL
import { server } from './src/test-utils/msw/server';

// MSW server lifecycle
beforeAll(() => server.listen({ onUnhandledRequest: 'warn' }));
afterEach(() => server.resetHandlers());
afterAll(() => server.close());

Hook	What it does
`beforeAll`	Starts the server before any test runs
`afterEach`	Resets handlers to defaults between tests (so one test's overrides don't leak)
`afterAll`	Shuts down the server after all tests complete

The onUnhandledRequest: 'warn' option logs a warning if your code makes a request no handler matches. In CI, switch this to 'error' so missed handlers fail the build:

const onUnhandledRequest = process.env.CI ? 'error' : 'warn';
beforeAll(() => server.listen({ onUnhandledRequest }));

💡 If your tests use fake timers, flush pending timers in afterEach before resetting handlers. Otherwise an animation timer scheduled inside a component can fire after the next test starts and trigger spurious failures.

Writing handlers

Each handler is a function that matches a request method and URL, and returns a response.

A basic handler for a REST API:

import { http, HttpResponse } from 'msw';

const BASE_URL = 'https://api.example.com';

export const handlers = [
  http.get(`${BASE_URL}/items`, () => {
    return HttpResponse.json([
      { id: 1, name: 'Item One' },
      { id: 2, name: 'Item Two' },
    ]);
  }),

  http.get(`${BASE_URL}/items/:id`, ({ params }) => {
    const { id } = params;
    return HttpResponse.json({ id: Number(id), name: `Item ${id}` });
  }),

  http.post(`${BASE_URL}/items`, async ({ request }) => {
    const body = await request.json();
    return HttpResponse.json({ id: 3, ...body }, { status: 201 });
  }),
];

A few things worth knowing: method-specific helpers (http.get, http.post, and the rest) match on HTTP verb, URL params like :id are extracted into params for you, the request body comes through await request.json(), and HttpResponse.json() returns typed JSON with whatever status code you pass.

Separating fixtures from handlers

Inline response objects work for a sketch. They don't work in a real codebase: the same shapes show up in handlers, in component tests, and in Storybook stories, and you don't want to maintain three copies.

Pull the fixture data into its own file:

// src/test-utils/msw/mockData.ts
export const mockItems = [
  { id: 1, name: 'Item One', createdAt: '2026-01-01T00:00:00Z' },
  { id: 2, name: 'Item Two', createdAt: '2026-01-02T00:00:00Z' },
];

export const mockProfile = {
  id: 'user_1',
  name: 'Warren de Leon',
  email: 'hi@example.com',
};

Handlers then read from mockData:

import { http, HttpResponse } from 'msw';
import { mockItems, mockProfile } from './mockData';

export const handlers = [
  http.get(`${BASE_URL}/items`, () => HttpResponse.json(mockItems)),
  http.get(`${BASE_URL}/me`, () => HttpResponse.json(mockProfile)),
];

Same fixtures get reused in component tests where you bypass MSW and pass data directly. One source of truth.

Handler sets for every scenario

Default success handlers are the starting point. But real apps need to handle failures too. This is where most MSW setups stop. Don't stop here.

The bugs that actually reach production aren't the happy-path failures. They're the awkward ones: the 401 that comes back mid-session because a token expired five minutes ago, the 429 from a burst of refresh attempts after a brief network blip, the 422 with a different validation shape than your form expects, the 408 that should have been a retry but wasn't. None of those get caught if your error coverage is "what if the API returns 500?".

I create separate handler sets for every error scenario the app needs to handle:

// Success (default)
export const handlers = [...apiHandlers, ...authHandlers];

// Server errors
export const errorHandlers = [
  http.get(`${BASE_URL}/items`, () => {
    return HttpResponse.json(
      { message: 'Internal server error' },
      { status: 500 }
    );
  }),
];

// Unauthorized (expired token)
export const unauthorizedHandlers = [
  http.get(`${BASE_URL}/items`, () => {
    return HttpResponse.json(
      { error: 'invalid_token', message: 'Token has expired' },
      { status: 401 }
    );
  }),
];

// Rate limiting
export const rateLimitHandlers = [
  http.post(`${BASE_URL}/auth/token`, () => {
    return HttpResponse.json(
      { error: 'too_many_requests', message: 'Try again in 60 seconds' },
      { status: 429, headers: { 'Retry-After': '60' } }
    );
  }),
];

// Timeout (never resolves)
export const timeoutHandlers = [
  http.get(`${BASE_URL}/items`, async () => {
    await new Promise(resolve => setTimeout(resolve, 60000));
    return HttpResponse.json({}, { status: 408 });
  }),
];

// Offline (network failure)
export const offlineHandlers = [
  http.get(`${BASE_URL}/items`, () => {
    return HttpResponse.error();
  }),
];

In my project, I have 11 handler sets:

Handler set	Status	What it tests
`handlers`	200	Default success responses
`errorHandlers`	500	Server error handling
`unauthorizedHandlers`	401	Expired/invalid token flows
`forbiddenHandlers`	403	Banned/suspended accounts
`conflictHandlers`	409	Duplicate registration
`validationErrorHandlers`	422	Form validation errors
`rateLimitHandlers`	429	Rate limiting with Retry-After
`emailNotConfirmedHandlers`	400	Email verification required
`storageErrorHandlers`	413/404	File upload/delete errors
`timeoutHandlers`	408	Network timeout simulation
`offlineHandlers`	Error	Complete network failure

Each set is exported and can be swapped in per test.

💡 Tip: The timeout handler uses await new Promise(resolve => setTimeout(resolve, 60000)) to simulate a request that never completes. Your code's request timeout will fire first, testing the timeout handling path.

Using handlers in tests

The default handlers run automatically (registered in setupServer). To test error scenarios, override them per test:

import { server } from '@app/test-utils/msw/server';
import { errorHandlers, unauthorizedHandlers } from '@app/test-utils/msw/handlers';

describe('API error handling', () => {
  it('shows error message on server failure', async () => {
    server.use(...errorHandlers);

    // Render component, trigger fetch, assert error UI
  });

  it('redirects to login on 401', async () => {
    server.use(...unauthorizedHandlers);

    // Render component, trigger fetch, assert redirect
  });

  // No cleanup needed - afterEach in jest.setup resets handlers
});

The spread (...errorHandlers) replaces matching handlers. Non-matching handlers from the default set remain active. After the test, server.resetHandlers() restores the defaults.

The custom render wrapper

MSW works best with a real Redux store, not a mocked one. The whole point is to test the actual integration: component → Redux thunk → HTTP request → MSW intercept → response → state update → UI update.

// src/test-utils/renderWithProviders.tsx
import React from 'react';
import { Provider } from 'react-redux';
import { combineReducers, configureStore } from '@reduxjs/toolkit';
import type { RenderOptions } from '@testing-library/react-native';
import { render } from '@testing-library/react-native';

import { itemsReducer } from '@app/features/Items';
import { authReducer } from '@app/features/Auth';

const rootReducer = combineReducers({
  items: itemsReducer,
  auth: authReducer,
});

type RootState = ReturnType<typeof rootReducer>;

function createTestStore(preloadedState?: Partial<RootState>) {
  return configureStore({
    reducer: rootReducer,
    preloadedState,
    middleware: getDefaultMiddleware =>
      getDefaultMiddleware({
        serializableCheck: false,
        immutableCheck: false,
      }),
  });
}

type AppStore = ReturnType<typeof createTestStore>;

interface ExtendedRenderOptions extends Omit<RenderOptions, 'wrapper'> {
  preloadedState?: Partial<RootState>;
  store?: AppStore;
}

export function renderWithProviders(
  ui: React.ReactElement,
  { preloadedState, store, ...options }: ExtendedRenderOptions = {},
) {
  const createdStore = store ?? createTestStore(preloadedState);

  const Wrapper = ({ children }: { children: React.ReactNode }) => (
    <Provider store={createdStore}>{children}</Provider>
  );

  return {
    store: createdStore,
    ...render(ui, { wrapper: Wrapper, ...options }),
  };
}

That covers Redux. Real apps usually need more: i18n, navigation, theming, toast context. The wrapper is the right place to compose them all: nest each provider around {children} exactly as App.tsx does, and wrap navigation-dependent screens in a NavigationContainer with an in-memory navigator. The principle: every provider that wraps your app at runtime should wrap your component in renderWithProviders. Anything you forget is a difference between test environment and runtime, and those differences are where flaky tests live.

Now your tests render with a real store, dispatch real thunks, and MSW handles the network:

it('loads and displays items', async () => {
  // Default handlers return success response
  const { getByText } = renderWithProviders(<ItemList />);

  await waitFor(() => {
    expect(getByText('Item One')).toBeTruthy();
  });
});

it('shows error state on failure', async () => {
  server.use(...errorHandlers);

  const { getByText } = renderWithProviders(<ItemList />);

  await waitFor(() => {
    expect(getByText('Something went wrong')).toBeTruthy();
  });
});

No manual mocking of dispatch, selectors, or fetch. The entire stack is real except the network.

Inline handler overrides

Sometimes you need a one-off response that doesn't fit any handler set. Define it inline:

it('handles unexpected response shape', async () => {
  server.use(
    http.get('https://api.example.com/items', () => {
      return HttpResponse.json({ unexpected: 'shape' });
    })
  );

  // Test that the code handles malformed responses gracefully
});

This is useful for edge cases like malformed JSON, missing fields, or unexpected status codes that don't warrant a full handler set.

Running the tests

With everything wired up, a single test file run looks like this:

yarn jest src/features/Items/__tests__/ItemList.rntl.tsx

PASS  src/features/Items/__tests__/ItemList.rntl.tsx
  ItemList
    ✓ loads and displays items (218 ms)
    ✓ shows error state on failure (94 ms)
    ✓ redirects to login on 401 (102 ms)
    ✓ surfaces rate-limit message (89 ms)

Test Suites: 1 passed, 1 total
Tests:       4 passed, 4 total

If you see a warning like [MSW] Warning: captured a request without a matching request handler, that's onUnhandledRequest: 'warn' doing its job. Either add a handler for the URL or fix the request your code is making.

If the suite hangs and never finishes, MSW is usually waiting on a request that never resolves. Most often this is a timeoutHandlers set that uses setTimeout(..., 60000) while the test environment still has real timers. Switch to fake timers in that test (jest.useFakeTimers() then jest.advanceTimersByTime(...)) or shorten the simulated delay.

Common pitfalls

Handlers are matched in order. If two handlers match the same request, the first one wins. When you call server.use(...overrides) the overrides are prepended, so they take priority over the defaults.

HttpResponse.error() simulates a network failure, not an HTTP error. The request never gets a response. Use that for offline scenarios. For HTTP errors (500, 401, and so on), reach for HttpResponse.json() with a status code.

If your handler reads the request body via request.json(), the handler function must be async. Forgetting this is one of the more common ways to end up with a handler that silently returns undefined.

Unhandled requests are silent by default. Always use onUnhandledRequest: 'warn' (or 'error' in CI) so missing handlers surface. A silent unhandled request means the test passes for the wrong reason.

A Response is not defined or TextEncoder is not defined error means the polyfills file isn't loading. Check that setupFiles: ['<rootDir>/jest.polyfills.cjs'] is in the Jest config, that the file extension is .cjs rather than .ts, and that the path is correct relative to rootDir.

A SyntaxError: Cannot use import statement outside a module thrown from node_modules/msw/ (or one of its dependencies) means that package isn't being transformed. Add it to the allow-list inside transformIgnorePatterns; the config above carries the full set for MSW 2.14.

Query strings don't participate in path matching: http.get('/api/items') matches /api/items?page=2 too, and the handler reads the parameters from request.url. If a test seems to ignore your query-specific handler, that's why.

Tests pass locally and fail in CI is usually onUnhandledRequest: 'error' catching a request you didn't realise your code was making in the CI environment, often analytics or crash reporting. Either add a handler for it, or strip those calls in test mode.

The full file structure

project-root/
  jest.config.cjs           # Jest config (preset, setupFiles, setupFilesAfterEnv)
  jest.polyfills.cjs        # TextEncoder, fetch, ReadableStream globals
  jest.setup.ts             # Server lifecycle, custom matchers, global mocks
  src/
    test-utils/
      msw/
        handlers.ts         # All handler sets (success, error, 401, etc.)
        server.ts           # setupServer with default handlers
        mockData.ts         # Fixture data used by handlers
      renderWithProviders.tsx  # Custom render with real store + providers
      index.ts              # Barrel export

The barrel export (index.ts) lets tests import common utilities from one place. For specific handler sets, import directly from the handlers file:

import { server, renderWithProviders } from '@app/test-utils';
import { errorHandlers, unauthorizedHandlers } from '@app/test-utils/msw/handlers';

The bottom line

The setup costs about thirty minutes. After that, every new test is simpler than the manual-mock equivalent. You write server.use(...errorHandlers) instead of jest.fn().mockRejectedValue(new Error('Network error')). The handlers are reusable across every test file. And the test is exercising integration behaviour, not mock behaviour.

The 11 handler sets in my project cover every error path the app handles. When I add a new API endpoint, I add handlers for it once, and every test that touches that endpoint gets correct mocking for free. The same handler-set approach also pairs well with E2E tests, where Detox + Cucumber drives the user flows and a separate runtime-mocking layer controls the API responses. The measure of the whole setup is that writing the next test is now easier than skipping it.

The code examples in this post are from rn-warrendeleon, my personal React Native project. The full MSW setup, handler sets, and custom render wrapper are all in the repo.

I built an app the hiring panel will never open

Warren de Leon — Mon, 27 Apr 2026 07:30:22 +0000

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

What the panel sees, and what they don't

A 7-page PDF attached to an email. That's the entire surface area the hiring panel ever touches. Not the wizard, not the timers, not the auto-save or the keyboard shortcuts or the colour-coded scores. The app exists for one person: the interviewer, during the call.

The PDF carries the work: scores, notes, strengths and growth areas, the hire/reject decision, and four appendices of evidence. Everything the panel needs to make an offer or move on.

Most hiring panels won't sit down with a code-review tool, and it'd be a strange ask if they did. Their job is the decision, not the data entry. The app's job is to make sure the data on the page is worth their attention.

Getting there took three attempts and a bug that nearly cost a candidate their score.

The format problem

I designed the scorecards for our React Native hiring process earlier this year. Three assessments: a 100-check code review, a walkthrough interview scored 1 to 5, and a behavioural interview mapped to our five values. The scoring worked. The format I was using to capture those scores during a live call did not.

The walkthrough interview is the hardest piece. A candidate is sharing their screen, talking you through the tech test they've built, explaining their decisions. I need to read a scripted question, listen, score it 1 to 5, write notes, check the time, then move to the next one. All while keeping eye contact and the conversation natural.

Try that in a markdown table in VS Code. The cursor lands in the wrong cell. The scroll position drifts. The candidate hears you typing and slows down.

Three attempts

Notion was my first thought. I use it for everything personal. It's not a tool we use at work, though, and building on a platform I'd be the only one using felt like a dead end. I dropped it before starting.

Markdown files came next. One .md per scorecard, tables for scores, space for notes. The code review worked well this way. 100 yes/no checks you complete after the interview at your own pace. The walkthrough and behavioural scorecards needed to work during the call, and the markdown got in the way. Finding the right row, typing a number, scrolling to the next section. Accurate, but slow. I was spending more attention on the document than the person.

After the interview was worse. Three separate markdown files in three different formats, manually stitched into one coherent document for the recruitment team. Every time, it took longer than I wanted.

The third attempt was a localhost React app. No backend, no database, no deployment. Just npm run dev and a browser tab. Everything persists in localStorage. The app dies when I close the tab and comes back when I open it again.

Staying present during the call

The whole point was to stop fighting the tool during the interview. Three things made the difference.

One question per screen. The walkthrough is a wizard. Each step shows the script to read aloud (in a blue blockquote so I can find it instantly), the questions with large 1 to 5 buttons, and a notes field. No scrolling. No hunting for the right section. Press "Next" and the next group appears. For senior candidates, the wizard extends from 4 steps to 8 with an additional Part B on system design.

Keyboard scoring. Press 1 through 5 and the score registers immediately. No clicking, no dropdown menus, no confirmation dialogs. My eyes stay on the video call. The scoring happens in my peripheral vision.

A section timer in the corner. Not a countdown, just a quiet elapsed-time display. I glanced at it during the first walkthrough and realised I'd spent 8 minutes on a section that should take 4. Without it, I'd have run over and cut the last section short. The candidate would have lost the chance to answer questions that could have lifted their score.

The bug that scored everyone the same

The stack was React 19, TypeScript, Vite, Tailwind v4. The first version had no state management library: a custom useLocalStorage hook and React Router.

During testing, I scored a candidate's walkthrough end to end. Every section, every question, full notes. I pressed "Next" to the summary screen and saw every section had the same score: whatever I'd entered on the last step.

A stale closure bug. Each wizard step's useCallback captured the walkthrough data from the previous render. When step 3 saved, it overwrote steps 1 and 2 because it was still holding the old state. The classic React problem where state inside a callback doesn't update when you think it does.

The fix was to stop trusting React's view of the data on writes. Every mutation reads the current candidate state directly from localStorage rather than from a captured closure. A freshCandidate() helper that hits localStorage.getItem on every save. Not elegant. Works every time.

function freshCandidate(id: string): Candidate | undefined {
  const raw = localStorage.getItem('ik-candidates');
  if (!raw) return undefined;
  return JSON.parse(raw).find((c: Candidate) => c.id === id);
}

The same pattern repeats across three hooks: useWalkthrough, useBehavioural, useCodeReview. Each one reads fresh, writes fresh, and dispatches a custom event (ls-sync) so other hook instances pick up the change. Twenty lines of persistence code. No Redux, no context providers, no middleware. Those twenty lines ran the first real interviews; the store was later formalised on Redux Toolkit as the app grew, but that's a different post.

The PDF nobody sees me build

After the interview, I press "Print / PDF" and the browser generates a Candidate Assessment Report. No PDF library. Just print CSS.

Page 1 is the summary: a score table, the recommended level band, the hire/reject decision, and the offer level. Pages 2 and 3 show strengths and growth areas pulled from all three assessments, grouped by source. Then four appendices: code review breakdown, walkthrough scores with every question and note, behavioural scores by value, and a level bands reference table with the candidate's band highlighted in navy.

That level bands table maps the combined score to one of 12 tiers: Graduate 1 through Senior 2+. (The four bands from the scorecard post got subdivided into three tiers each once real candidates started landing between them.) The 2+ tier is deliberately hard to reach. It marks someone at the very top of their category, pushing into the next. When a panel member sees "Associate 2+" on the PDF, the read is immediate: strong Associate, not quite SE. That single label carries more signal than a paragraph of justification.

The behavioural gate adds a second check. A candidate scoring below 10/25 on values doesn't proceed, regardless of their technical score. Between 10 and 14 triggers a panel discussion. 15 or above clears the gate. Technical skills can be taught. Values mismatches create problems that grow over time.

Print CSS is its own discipline

I wrote more CSS for @media print than for screen. It's the part that surprised me the most.

The navy background on the combined score box? Doesn't print. Browsers strip background colours by default. I had to convert it to a white box with a heavy black border using [style*="background: #002147"] selectors in the print stylesheet. Tailwind utility classes like bg-white get targeted with attribute selectors ([class*="bg-white"]) to override padding, borders, and margins for print.

page-break-inside: avoid is a suggestion, not a command. The browser will break inside an element if the alternative is a mostly-empty page. I spent an hour debugging why a strengths section split across two pages before I realised the content was simply too tall for the remaining space.

Heading styles needed explicit inline border-bottom because Tailwind classes get stripped or overridden by the print reset. Font sizes switch from rem to pt. Interactive elements (textareas, checkboxes, dropdowns) are hidden. The entire print layout lives in a separate CandidatePrintReport component that renders inside hidden print:block. Clean separation. The screen never sees the print layout, the print never sees the buttons.

If I built this again, I'd design the print layout first and the screen layout second. The PDF is the artefact that matters. The screen is the input form.

What I'd change

Tests before scoring logic. Red flag deductions, stretch bonuses, level band lookups, the behavioural gate threshold. These are pure functions now, extracted into utils/scoring.ts, and they're the kind of code that breaks silently when you tweak a boundary. I wrote them last. They should have been first.

The markdown import parser is fragile. It uses regex to read Y/N values from scored code review files. It works for the specific format I designed, but a different table layout or an extra column breaks it. A proper parser with error recovery would hold up better.

Accessibility was added late. WCAG AA compliance (per-route page titles, heading hierarchy, colour-contrast ratios, roving tabindex on score selectors, aria-live on save indicators) was retrofitted rather than built in. It all passes now. It would have been cleaner to build accessible from the start. Internal tools deserve the same standards as public-facing ones.

The real test

I used this app for the first time in an actual interview last week. The candidate didn't know I was using anything unusual. They presented their take-home submission, I scored, we talked. No scrolling, no typing into markdown tables, no losing my place. After the call, one button press and the PDF was ready.

That's the whole point. The best interview tool is the one the candidate never notices. The scoring, the timers, the level calculations, the PDF generation: all of it should sit out of the way. The panel reads the PDF. The candidate has a conversation. The tool stays quiet between the two.