DEV Community: Warren de Leon

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.

So far the host has loaded one screen from one remote. A real app is more than a screen: it has a shell, a tab bar, somewhere to put the features. This post makes the host that shell. It owns the navigation and the tab bar, and each tab is a separate remote, built and deployed on its own, loaded at runtime.

The shape we're building, before any code: the host owns the tab bar, and each tab is a separate remote app, fetched and run at runtime the first time you open it.

📊 Diagram: view it on warrendeleon.com

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

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, profile, 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 and install its dependencies exactly as you did for list.

The screen it exposes, apps/profile/src/ProfileScreen.tsx. It reads the safe-area inset from the host's provider, the same shared singleton from post 3:

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

const TRAINER = { name: 'Ash Ketchum', region: 'Kanto', badges: 8, caught: 151 };

export default function ProfileScreen() {
  const insets = useSafeAreaInsets();
  return (
    <View style={[styles.screen, { paddingTop: insets.top + 24 }]}>
      <Text style={styles.title}>Trainer</Text>
      <Text style={styles.subtitle}>Served by the profile remote</Text>
      <View style={styles.card}>
        <Text style={styles.name}>{TRAINER.name}</Text>
        <Text style={styles.meta}>
          {TRAINER.region} · {TRAINER.badges} badges · {TRAINER.caught} caught
        </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 },
  card: {
    padding: 16,
    borderRadius: 12,
    borderWidth: StyleSheet.hairlineWidth,
    borderColor: '#e5e7eb',
    backgroundColor: '#f9fafb',
  },
  name: { fontSize: 18, fontWeight: '600', marginBottom: 4 },
  meta: { fontSize: 14, color: '#6b7280' },
});

Its container entry, apps/profile/src/index.js, stays empty, because a remote boots nothing of its own:

export {};

Its apps/profile/rspack.config.mjs is the list config with a different name, exposed screen, and the same shared singletons:

new Repack.plugins.ModuleFederationPluginV2({
  name: 'profileApp',
  filename: 'profileApp.container.js.bundle',
  exposes: {
    './ProfileScreen': './src/ProfileScreen.tsx',
  },
  dts: false,
  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'],
    },
  },
}),

Give it its own dev server port so it does not collide with list on 8082. In apps/profile/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. The host installs a navigation library; the remotes stay plain screens that know nothing about tabs. Install it in the host only:

cd apps/host
npm install @react-navigation/native @react-navigation/bottom-tabs react-native-screens
cd ios && bundle exec pod install

react-native-screens is a native module, so the host needs a pod install and a fresh native build. react-native-safe-area-context is already there from post 3, and React Navigation uses it.

Here is the important point about sharing, and it is the post-3 contract in reverse. React Navigation lives only in the host because only the host uses it. The remotes never import it, so there is nothing to share. The shared singletons stay exactly what they were: react, react-native, and react-native-safe-area-context. A library only needs sharing when code on both sides of the boundary touches it.

The shell

Rewrite apps/host/App.tsx. The host now owns a SafeAreaProvider, a NavigationContainer, and a bottom tab navigator. 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 ProfileScreen = React.lazy(() => import('profileApp/ProfileScreen'));

// 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 ProfileTab = withSuspense(ProfileScreen);

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="Trainer" component={ProfileTab} />
        </Tab.Navigator>
      </NavigationContainer>
    </SafeAreaProvider>
  );
}

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

Each tab is a remote behind React.lazy and Suspense. The remote downloads the first time you open its tab, not at launch, so the app starts on the first tab and fetches the second only when you switch to 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`,
  profileApp: `profileApp@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 'profileApp/ProfileScreen' {
  import type React from 'react';
  const ProfileScreen: React.ComponentType;
  export default ProfileScreen;
}

Run it

Four terminals now, one per remote and one for the host, plus the build:

cd apps/list && npm run start:remote      # :8082
cd apps/profile && 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. Tap Trainer and the host fetches the profile remote from 8083, runs it, and shows the trainer card. Two features, built and served by two separate apps, sitting in one tab bar that belongs to neither of them.

What you built, and what's next

The host is a shell now. It owns the 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. Adding a third feature is adding a third remote and a third tab, 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: the tabs stop holding hardcoded data and start sharing one store. A single RTK Query cache across remotes, real data from an API, and cross-module dispatch.

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-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@latest init Host --directory apps/host
npx @react-native-community/cli@latest init List --directory apps/list

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 @module-federation/runtime @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 has the native iOS project, the remote is JS-only. 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.2): 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 rule on downloaded interpreted code

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
│   ├── 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/*/!(index)', '@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 pattern blocks any import that reaches into another feature's internals. 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.

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 15+ with Command Line Tools, plus an iOS simulator created (e.g. iPhone 17 Pro)
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 with USB debugging on. 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.

.detoxrc.js

The Detox configuration defines your app builds and device targets:

module.exports = {
  testRunner: {
    args: {
      config: '.cucumber.js',
    },
    forwardEnv: true,
  },
  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 17 Pro' },
    },
    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'],
    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 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 are exposed as globals at runtime, but TypeScript needs to be told they exist. Add "types": ["detox", "node"] to your tsconfig.cucumber.json (we did this in step 2), or import them explicitly with import { device, element, by, waitFor } from 'detox'. Skip both 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();
  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.

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 class that listens to Cucumber events:

const { Formatter } = require('@cucumber/cucumber');

class CheckmarkFormatter extends Formatter {
  constructor(options) {
    super(options);

    options.eventBroadcaster.on('envelope', (envelope) => {
      if (envelope.testStepFinished) {
        this.onTestStepFinished(envelope.testStepFinished);
      }
      if (envelope.testCaseFinished) {
        this.onTestCaseFinished(envelope.testCaseFinished);
      }
    });
  }

  onTestStepFinished(event) {
    const { testStepResult } = event;
    const icon = testStepResult.status === 'PASSED' ? '✓' :
                 testStepResult.status === 'FAILED' ? '✗' :
                 testStepResult.status === 'SKIPPED' ? '○' : '?';
    const color = testStepResult.status === 'PASSED' ? '\x1b[32m' :
                  testStepResult.status === 'FAILED' ? '\x1b[31m' : '\x1b[33m';
    this.log(`${color}  ${icon}\x1b[0m ${this.getStepText(event)}\n`);
  }
}

module.exports = CheckmarkFormatter;

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": "DETOX_WORKERS=2 yarn detox:ios:test --parallel 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 17 Pro 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.
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.

When an E2E test fails, you should know what broke without reading the test code.

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.

Tiered secure storage in React Native

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',
  BIOMETRIC_PREFERENCE = 'biometricPreference',
  HASHED_PIN = 'hashedPIN',
  ENCRYPTION_KEY = 'encryptionKey',
}

const SERVICE_PREFIX = 'com.warrendeleon.portfolio';

export const SecureStore = {
  async set(key: SecureStoreKey, value: string): Promise<boolean> {
    await Keychain.setGenericPassword(key, value, {
      service: `${SERVICE_PREFIX}.${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 or device passcode. BIOMETRY_ANY_OR_DEVICE_PASSCODE means the user needs Face ID, Touch ID, or their device PIN to read the value. If the device has no security set up, the OS still protects the data.
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'],
  blacklist: ['user', 'error', 'isLoading'],
};

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:

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);
        const { data } = await axios.post('/auth/v1/token', {
          grant_type: 'refresh_token',
          refresh_token: refreshToken,
        });

        // 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.
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 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. Setup takes an afternoon.

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)/)',
  ],
  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|until-async to the allow-list or you'll see SyntaxError: Cannot use import statement outside a module from inside node_modules/msw/.

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';
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/notification context. The wrapper is the right place to compose all of them. Add providers around {children}:

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

If a screen uses react-navigation, wrap it in NavigationContainer and an in-memory navigator for the test. The principle is the same: every provider that wraps your app in App.tsx 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/ means MSW isn't being transformed. Add msw|until-async to the allow-list inside transformIgnorePatterns.

Trailing slashes matter: http.get('/api/items') won't match a request to /api/items/. Match exactly what your code sends, or use a path pattern like http.get('/api/items*', ...).

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, but those are topics for later posts.

If writing the next test is harder than skipping it, your test infrastructure is the problem.

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 is React 19, TypeScript, Vite, Tailwind v4. 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('hl-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.

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

How to write a take-home tech test that candidates actually want to do

Warren de Leon — Mon, 20 Apr 2026 07:30:11 +0000

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

The test nobody finishes

Most take-home tech tests fail before the candidate writes a single line of code.

They clone the repo. They run npm install. Something breaks. Forty-five minutes later they're debugging a Ruby version mismatch, a missing CocoaPod, or a Node version that doesn't play with the bundler. By the time the app runs they've burnt through their patience and half their evening.

The best candidates, the ones you actually want to hire, are the most likely to walk away. They have options. They'll pick the company that respects their time.

The classic version of the take-home does have a logic to it. A prescriptive brief with a fixed stack gives you comparable submissions across candidates, and the rough edges in setup do filter for grit. If you're hiring high volumes for one narrow role, that signal is useful. For a small team hiring across levels, where two senior engineers will probably reach for different state libraries on day one, you're filtering on the wrong thing.

Our first take-home candidate made the point for me. Two hours fighting Ruby versions before any application code was written. System Ruby too old, the version manager and the vendored bundler at odds at every step. Back-and-forth messages all the way through. Zero lines of code at the end of it.

The questions were fine. The developer experience was the problem.

Treat the test like a product

The tech test is the first real interaction a candidate has with your engineering culture. Everything they touch tells them something about you.

If the setup is broken, they think your codebase is broken.
If the brief is vague, they think your specs are vague.
If the timeline is unrealistic, they think your deadlines are unrealistic.

So I treat the test the same way I'd treat a product:

Product thinking	Applied to the tech test
User research	What frustrates candidates about tech tests?
Clear requirements	A detailed brief with wireframes and rules
Developer experience	Starter project, setup script, path aliases
Documentation	Linked guides for every question they might have
Continuous improvement	Update after every round based on what went wrong

After the Ruby incident I added a setup script, pinned the Ruby version, committed a Gemfile.lock with a modern bundler, and added a troubleshooting section to the README. The next candidate was coding in under two minutes.

The setup script

The single biggest improvement was a setup.sh that handles everything.

./setup.sh

One command. It:

Checks Node version (installs via nvm if needed)
Checks Ruby version (supports rbenv, rvm, and asdf)
Checks for Xcode CLI tools and CocoaPods
Runs yarn install
Runs bundle install and pod install
Tells you exactly what to fix if something is wrong

The key design choice: the script asks before installing anything. It detects what the candidate already has and works with it. Someone using rbenv gets rbenv. Someone using rvm gets rvm. Their environment is respected, not overwritten.

Pin your versions in the repo. .ruby-version, .nvmrc, Gemfile.lock with a modern bundler. Then write a setup script that reads them. Every minute a candidate spends on setup is a minute they're not spending on code.

The starter project

I give candidates a fully configured project. Not a blank repo. A working app.

Included	Why
TypeScript in strict mode	No ambiguity about language expectations
React Navigation v7 with typed params	Navigation is boilerplate, not a test of skill
Jest + React Native Testing Library	Configured with native module mocks, ready to write tests
ESLint + Prettier	Consistent code style from line one
Path aliases (`@app/*`)	No `../../../` import chains
Custom test render wrapper	NavigationContainer included, just render and assert
Three placeholder screens	"Replace me", clear starting point
A passing smoke test	Proof the setup works before they change anything

Everything compiles. Everything runs. The smoke test passes.

I'm not testing whether someone can configure a bundler or debug a TypeScript path alias. I'm testing whether they can build application code. The starter project removes every obstacle between "I cloned the repo" and "I'm writing my first component."

Some candidates start from scratch anyway. That's fine, the starter is optional. Most use it, though, and instead of spending their first hour fighting config they spend it making architectural decisions.

The brief: clear about what, not how

Some tech tests specify exactly how to build things. Which state management library, which folder structure, which API client. That approach pays off when you need apples-to-apples submissions, or when the role really is about working within tight conventions. For us, those decisions are the most interesting part of the submission, so locking them down would throw away the signal we actually want.

Our brief takes the opposite approach. It explains what the app should do in detail and says nothing about how.

Screen wireframes show the data and interactions (ASCII layouts, not pixel designs)
A requirements table spells out the rules (max 6 items, add from detail, remove from list)
A technical requirements table lists the non-negotiables (React Native, TypeScript, React Navigation)

What's deliberately missing: architecture prescriptions. The candidate chooses the state management, the folder structure, the API client, the testing strategy.

A candidate who picks Redux Toolkit tells me something different from one who picks Zustand. Neither is wrong. Both are interesting. The reasoning behind the choice is what the walkthrough conversation is built on.

If your brief specifies the architecture, you're testing compliance, not engineering. The briefs that work for us describe the what in detail and leave the how completely open.

Respecting people's time

Candidates get 7 days. The work should take 4 to 6 hours.

We say that explicitly, in the brief and in the submission guide, twice, because people miss it the first time.

7 days gives flexibility. Some people work across a weekend. Some do an hour each evening. Some block a Saturday morning. The timeline respects that candidates have jobs, families, and lives outside of interviewing.

The 4-to-6-hour estimate is honest. I built the test myself to check it. A competent React Native developer can build all three screens with state management, API integration, basic tests, and a README in that time. Some choose to invest more. That's their call, not our expectation.

If a candidate needs more time, we give it. No questions asked. Going silent and submitting three days late with no explanation is a different signal from sending a message saying "I need a couple more days." Communication matters.

Tell them what you're looking for

Early on, a candidate spent an hour styling buttons because they'd assumed UI polish mattered to us. It didn't. We were looking at architecture and testing. That hour was wasted on our behalf, not theirs, because we hadn't told them what counted.

Now we're explicit:

How you think about architecture and code organisation
How you break down a problem into components and data flows
How you make and justify technical decisions
How you handle edge cases and error states
How well you know your own code

We're NOT judging visual design or pixel-perfect UI
We're NOT expecting a production-ready app in a take-home

When candidates know we care about architecture and trade-offs more than styling, they spend their time accordingly. Better signal for us, better experience for them.

We also tell them upfront that we might use automated tooling as a pre-check, but every submission is manually reviewed and scored by the hiring panel. Transparency builds trust.

The walkthrough is a conversation

The candidate drives for the first 10 minutes:

Demo the app. Walk through all screens, show the features working.
Run the tests. Show them passing live.
Walk through the code. Explain structure and decisions.

After the presentation, we ask questions. The framing matters. We say:

"Don't worry if something doesn't work as expected during the demo. That happens. If it does, just talk me through what you think went wrong and how you'd fix it. That tells me more than a perfect demo would."

The point is signal, not politeness. Watching someone diagnose a bug in their own code is one of the strongest reads you can get on an engineer. A candidate who says "Oh, I think the useEffect dependency array is wrong here" is showing you exactly how they work.

A perfect demo shows you nothing except that they rehearsed.

Documentation as a first-class feature

The test comes with proper documentation. Not just a README. A set of linked markdown files:

Document	What it covers
Assessment Brief	Requirements, screen wireframes, party rules, technical requirements
API Guide	Endpoints, GraphQL vs REST options, client recommendations
Starter Project	What's included, project structure, available commands, testing setup
Submission & Walkthrough	How to submit, what happens in the walkthrough, tips
Stretch Goals	Optional extras and what each one demonstrates

Every question a candidate might have is answered before they need to ask it. The goal is to take ambiguity off the table. I don't want to evaluate how well someone interprets a vague brief. I want to evaluate how they build software when the requirements are clear.

What I'd change next time

The test isn't finished. What's on my list:

A video walkthrough of the starter project. A 3-minute Loom showing the folder structure, how to run it, and where to start. Some people learn better from video than docs.
A .env.example file. The test uses a public API with no keys, but committing the file sets the right pattern.
Running the setup on a clean machine before every hiring round. A developer laptop accumulates years of tooling, and any assumption that "everyone has this installed" tends to break the moment a candidate runs the script on a fresh OS install.

The structure is right though. Setup script. Starter project. Clear brief. Honest timeline. Proper documentation. Transparent evaluation criteria.

If you're designing a tech test and candidates keep dropping out, don't look at the questions first. Look at the developer experience. The best tech test is one where the candidate spends 100% of their time on the thing you're actually evaluating, and 0% on everything else.

This is the last in a series about building a hiring process from scratch. The earlier posts cover why I redesigned the test, advice for candidates taking one, and how the scoring works.

How I designed a tech test scorecard that works from Graduate to Senior

Warren de Leon — Mon, 13 Apr 2026 07:30:10 +0000

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

The problem with "is this a 3 or a 4?"

When I started building the hiring process for my squad, I wanted a structured scorecard from the start. I wrote about the tech test itself in an earlier post. The test worked. The scoring didn't. At least, not the way I first designed it.

My first scorecard used a 1 to 5 scale for each criterion. "TypeScript usage: score 1 to 5." "State management: score 1 to 5." Each criterion had a rubric describing what each score meant. On paper it looked fine.

Then I tried to use it.

Two people reviewed the same submission. One scored the TypeScript a 3 ("types are there but not strict"). The other scored it a 4 ("clean types throughout, good use of typed hooks"). They were both looking at the same code. They just read the rubric differently. If two reasonable people can disagree on the score, the rubric isn't specific enough. The problem isn't the reviewers, it's the tool.

Checklists over rubrics

The fix was simple: replace every subjective score with a yes/no checklist.

A single criterion, before and after. This is TypeScript usage:

Before: subjective rubric

Score	Description
5	Strong typing throughout, strict mode, generics where appropriate
4	Clean types, minimal `any`, props and navigation typed
3	Types for main structures, some `any` leakage, works but not strict
2	TypeScript used poorly, frequent `any`, adds little safety
1	`any` everywhere, effectively JavaScript with `.tsx` extensions

The problem: "clean types" and "types for main structures" are both reasonable descriptions of the same code. One reviewer sees a 3, another sees a 4. Both are right.

After: observable checklist

✅ Source files use .ts/.tsx extensions
✅ Interfaces or types exist for API data, state shape, and component props
✅ Navigation params are typed
✅ Zero any in production code
☐  Typed hooks used (useAppSelector, useAppDispatch)
☐  Strict TypeScript enabled
☐  Zod or Yup schemas for validation

Same criterion. Seven checks. Each one is a fact you can verify by looking at the code. Two reviewers will tick the same boxes because there's nothing to interpret.

The first four checks are baseline (any competent candidate will have these in a 4 to 6 hour submission). The last three are signals of deeper experience. The ordering does the levelling for you.

I did this for every criterion across four sections:

Core Functionality: does the app work?
Data Layer & API: how does it fetch and manage data?
Code Quality: is the code well-written and well-organised?
Testing: is it tested, and how?

100 checks. 100 points. One point each.

Same test, different ceiling

The checks are ordered by how much investment they represent.

The first few checks in each criterion are things any competent candidate will hit in 4 to 6 hours:

Does the FlatList render items?
Does pagination work?
Does the party screen have an empty state?
Are there types for the main data structures?
Is there at least one test file?

These are the baseline. If you built the thing the brief asked for, you pass these.

The later checks need more time, more years on the job, or both:

GraphQL instead of REST
Runtime response validation with Zod
MSW for HTTP mocking in tests
Feature-first project structure
BDD with Cucumber
Coverage thresholds enforced

You don't do these in a weekend. They're patterns you pick up from shipping real apps.

A candidate spending 4 to 6 hours scores in the 50 to 65 range. A candidate spending a full week with years behind them might score 85 to 95. The brief is the same. The expectations scale with the score.

How the levels map

The total score maps directly to a level:

Level	Code review score
Graduate	20 to 45
Associate	46 to 64
Software Engineer	65 to 88
Senior	89 to 100

The code review score isn't the whole picture. The walkthrough call adds more signal. The code review is the foundation.

Respecting the time constraint

A tech test isn't a production app. Candidates have jobs, families, lives. They're giving you their evening or their weekend. Marking someone down for not implementing a caching layer or not co-locating their styles would be like marking down a timed essay for missing footnotes.

That's why the baseline checks matter. Getting all of them right scores you around 50 to 65 out of 100. That's Associate to Software Engineer territory. On my old rubric, a "3 out of 5" sounded like a consolation prize. 55 out of 100 on the checklist is a positive result with a clear path to the next level.

What "above baseline" looks like

The later checks are where candidates stand out. These aren't requirements. They're signals.

A candidate who adds Detox E2E tests with extracted helpers is telling me something about their testing culture. One who implements GraphQL with Apollo is telling me something about their API thinking. One who sets up MSW with multiple handler sets (success, error, 401, timeout, offline) is telling me they've debugged real API failures before.

None of these are required. All of them are noticed.

The stretch goals sit on top of the 100 points as bonuses: search, dark mode, accessibility, i18n, feature-first structure, Storybook, ErrorBoundary. These are the marks of someone who had time and chose to spend it well.

The walkthrough changes everything

The code review gives me a number. The walkthrough gives me context.

A candidate who scores 65 on the code review might jump to 85 after the walkthrough if they can explain every trade-off, say what they'd change with more time, and navigate their codebase from memory. The number measures what they built. The conversation measures how they think.

I designed the walkthrough as a set of question tables. Each question has five signal descriptions, from "can't find the code" to "explains it from memory with edge cases." The interviewer ticks one row per question. No more "was that walkthrough a 3 or a 4?"

For Senior candidates there's an additional system design section in the same call. No separate interview. The last 15 to 20 minutes shift from "show me your code" to "how would you design this for a team of 20 engineers?" The same question tables, the same tick-one-row format.

What I learnt building this

A few lessons that stuck:

Start with checklists, not rubrics. Every time I wrote a rubric ("5 = excellent, 3 = good, 1 = poor"), it turned into a debate about what "good" means. Checklists end the debate. Either the thing is in the code or it isn't.

Order the checks by investment, not importance. The first checks aren't more important than the last. They're just more reachable in 4 to 6 hours. A Senior candidate who skips check 3 but nails check 7 isn't punished for the skip because the total still reflects their level.

Separate what you can see from what you need to ask. The code review scorecard is 100% observable from the code. No "is the architecture clean?" questions. The walkthrough is 100% conversational. No code-reading during the call. Each document has one job.

Respect the time constraint. If a check would need more than 6 hours of work from a competent Software Engineer, it belongs in the upper half of the checklist, not the baseline. I kept catching myself writing baseline checks that were really Senior expectations. The question I kept asking: "Would I expect this from someone doing this test after work on a Wednesday evening?" If the answer was no, it moved up.

It's still evolving

I've used this scorecard for our first round of React Native hiring. My peer EM reviewed it and adopted it for his squad's hires too. That's the test of a good system: someone else can pick it up and use it without you in the room.

I'm not pretending it's perfect. The bands might need recalibrating after more candidates go through. Some checks might turn out to be too easy or too hard. The stretch goals might need rebalancing.

The structure is right though:

Checklists, not rubrics
Observable facts, not opinions
Ordered by investment
Same test for everyone
Different ceiling for different levels

If you're building a hiring process and your interviewers keep disagreeing on scores, try replacing your rubric with a checklist. You might be surprised how much agreement you get when you stop asking "how good is this?" and start asking "is this here?"

If you want the candidate's view on what this scorecard measures, I wrote a companion post: How to pass a React Native tech test.

The best scoring systems don't measure how you feel about the code. They measure what's in the code.

How to pass a React Native tech test

Warren de Leon — Mon, 06 Apr 2026 07:30:11 +0000

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

What panels actually score on

I review React Native tech test submissions. Most rejections aren't a coding problem. The candidate could code. They didn't show the right things.

This post is the advice I'd give a friend before they submitted a take-home. Specific, practical, panel-side. The shifts that move a submission from "maybe" to "yes."

I wrote about why I redesigned a tech test from the hiring manager's perspective in a separate post. This one is the other side: how to pass one.

Read the brief twice. Then read it again

Sounds obvious. It's the most common miss.

If the brief says "build three screens with navigation," don't build two. If it says "use TypeScript," don't use JavaScript. If it says "manage a list of up to 6 items," make sure adding a 7th is handled gracefully.

Reviewers check requirements like a checklist. Every missing requirement is points dropped. Following a spec is part of the job. If you miss requirements in a tech test with a clear brief, what happens with a vague Jira ticket? Read the brief before you start, read it again halfway through, and read it one final time before you submit.

Project structure tells the panel how you think

The first thing I do when I open a submission is look at the folder structure. Before I read a line of code, the layout already says something about how you organise work.

Type-first structure (screens/, components/, hooks/, services/):

src/
  components/
  hooks/
  screens/
  services/
  types/

Feature-first structure (each feature is self-contained):

src/
  features/
    product-list/
    product-detail/
    favourites/
  shared/
    components/
    hooks/

Neither is wrong. Feature-first shows you've thought about how the app scales. If I ask "what happens when 5 teams work on this codebase?" and your structure already answers that question, you're ahead.

Red flag: everything in a flat src/ folder with no organisation. It suggests the coding started before the architecture was planned.

TypeScript is not optional

If the brief says "TypeScript preferred," treat it as required. Submitting plain JavaScript in 2026 is an automatic downgrade.

Using TypeScript isn't the bar. Using it well is:

Do this	Why it matters
Type your props	Every component should have a typed props interface
Type your API responses	Don't use `any` for data from the server
Type your navigation params	React Navigation has good TypeScript support

The one any I'll forgive: a third-party library type that would take an hour to model properly. Acknowledge it in a comment. // TODO: type this properly, ran out of time reads better than pretending it isn't there.

Red flag: any scattered throughout the codebase with no acknowledgment.

State management: pick something and own it

I don't care whether you use Redux Toolkit, Zustand, React Context, or Jotai. I care that you picked it deliberately and can explain why.

Choice	What it signals
Context for a three-screen app	Reasonable. Lightweight, no dependencies.
Redux Toolkit for a three-screen app	Fine, but I'll ask why. "It's what I know best" is an honest answer.
Zustand with a clean store	Shows you're current with what's in active use across recent RN codebases.

If you go with Redux, use Redux Toolkit. Not the old switch/case reducer pattern. If I see createStore instead of configureStore, or manual action type constants instead of createSlice, the Redux knowledge probably needs refreshing.

What actually matters:

✅ State logic separated from the UI
✅ Actions, reducers, and selectors in their own files
✅ Business rules (like max party size) enforced in the state layer
✅ Updates are predictable
❌ Business logic living inside components
❌ State scattered across useState calls with no pattern

Don't dispatch a fetch every time a screen mounts. If I navigate to a detail screen, go back, and return to the same detail screen, I shouldn't see a loading spinner again. A simple if (!data[id]) check before your dispatch(fetchDetails(id)) is enough.

Tests: quality over coverage

You don't need 90% coverage. You need meaningful tests. Three good tests beat twenty snapshot tests.

What I want to see:

Test type	Example
Business logic	If there's a rule (max 6 in a list, no duplicates), test it. Reducers and selectors are the highest-value tests.
User interactions	Render a component with RNTL, press a button, check the result. Use `render`, `fireEvent`, `waitFor`.
Edge cases	What happens when you add a duplicate? When the list is empty? At the pagination boundary?
Passing tests	Run them before you submit. Failing tests signal unfinished work.

What I don't want to see:

❌ Snapshot tests everywhere. They break on every UI change and prove nothing about behaviour.
❌ Tests that mock everything. If your test mocks the function it's testing, it's testing the mock.
❌ No tests at all. Hard to recover from in the walkthrough.

Aim for 5 to 10 focused tests covering the critical paths. Reducers, selectors, key interactions. That's enough.

Handle loading, errors, and empty states

This is where candidates stand out. Anyone can build the happy path. The question is: what happens when things go wrong?

State	What to do
Loading	Show a spinner or skeleton on first load. Show a subtle indicator during pagination. Don't flash a full-screen spinner for 100ms.
Error	If the API fails, tell the user. A retry button is better than nothing. An informative message beats "Something went wrong."
Empty	If the list is empty or there are no saved items, show something useful. Not a blank screen.

Red flag: the app crashes on a slow network. No loading state, no error handling. The reviewer opens DevTools, throttles the network, and the app falls apart.

The API call matters

GraphQL vs REST. If the brief offers both, the choice matters less than the execution. A well-implemented REST client beats a messy GraphQL setup. Pick the one you can do cleanly, and be ready to explain why.

Use FlatList or FlashList. Never ScrollView for lists. ScrollView renders every item at once. With 100+ items, you'll see frame drops, memory spikes, and eventual crashes. FlatList virtualises the list, only rendering what's on screen. A ScrollView wrapping a .map() over a data list suggests a gap in understanding RN's rendering model.

Other things that get noticed:

✅ Caching: don't refetch data you already have
✅ Pagination: don't fetch 1000 items on first load
✅ ErrorBoundary: catches JavaScript errors and shows a fallback instead of a white screen

Edge cases are where you stand out

The happy path is the minimum. What separates a Software Engineer submission from a Senior one is edge case handling:

Full list? What happens when someone tries to add a 7th item? A toast, a disabled button, a modal. Anything except silently failing.
Empty list? Show a meaningful empty state, not a blank screen.
Rapid taps? Does pressing "add" five times fast cause duplicates or crashes?
Back navigation? When I go from detail back to the list, is my scroll position preserved?
End of list? Does pagination stop cleanly when there's no more data?

You don't need to handle all of these. Handling some of them shows you think about real users, not just passing requirements.

The README is part of the test

Write a README. Not a novel. A short document that covers:

Section	What to write
How to run it	`yarn install`, `yarn ios`, done. Extra steps documented.
What you built	One paragraph summary.
Decisions you made	Why this state management? Why this folder structure? Two sentences each.
What you'd improve	The most important section. It shows self-awareness.

The "what I'd improve" section is a cheat code. It lets you acknowledge shortcuts without the reviewer discovering them as flaws. "With more time, I'd add E2E tests with Detox and implement proper caching" turns a missing feature into a demonstration of judgement.

The walkthrough: this is where jobs are won

If the test has a walkthrough call, prepare for it. The code gets you into the room. The walkthrough gets you the offer.

Know your code. If I say "show me where you handle the API response," you should navigate there in under 5 seconds. Hesitation raises questions about how well you actually know the codebase.

Explain your trade-offs without waiting to be asked. When you show a section of code, say "I chose this approach because X, but I know the trade-off is Y." That's the answer I'm looking for before I even ask the question.

Be honest about shortcuts. "I used Context here because it was faster, but in a production app I'd move to Zustand once the state got more complex." Strong answer. "I think Context is the best approach" is weaker, because the panel knows the trade-offs and you've just suggested you don't.

Have a list of improvements. When I ask "what would you change with more time?" the worst answer is "nothing, I'm happy with it." The best answer is a prioritised list: "First I'd add caching, then E2E tests, then refactor to feature-first folders."

Ask questions back. The best walkthroughs are conversations, not presentations. Ask about the team's architecture, their testing approach, their deployment process. It shows you're evaluating the role, not just hoping to pass.

Stretch goals: do them, but do them well

If the brief mentions optional extras, pick one or two you can do well. Don't try to do all of them poorly. One well-executed stretch goal is worth more than three half-finished ones.

Worth picking	Why
Search/filter	Quick to implement, immediately visible, shows UX thinking.
Accessibility	Labels, roles, contrast. Most candidates skip this. Even basic accessibility makes you stand out.
Error/offline handling	A retry button when the network fails. Shows real-world thinking.

Avoid unless you can do them properly	Why
Animations	Half-finished animations look worse than none.
Dark mode	Inconsistent across screens is a liability.

The mistakes that actually cost people the job

These are about signals, not code quality.

Mistake	Why it hurts
Not reading the brief properly	Missing a core requirement. Building two screens when the brief says three.
No tests at all	Even two or three tests show you care about quality. Zero is a strong negative signal.
AI-generated code you can't explain	Using assistance is fine. Submitting code you don't understand is not. The walkthrough surfaces it quickly.
Overengineering	A tech test doesn't need a design system and a micro-frontend architecture. Build what the brief asks for, well.
Submitting late without communicating	If you need more time, ask. Going silent and submitting three days late is a red flag.

The one thing that matters most

Show that you think. Coding is the baseline, not the differentiator.

Anyone can build screens. The candidates who get hired demonstrate judgement: why they chose this approach, what they'd do differently, where the code would break at scale, what tests actually matter.

The tech test is checking whether you can make good decisions and communicate them clearly. The React Native code is the medium, not the question.

Build something clean, test the important parts, document your thinking, and be ready to talk about it honestly. That's the whole secret.