+1 (415) 943-4271

Feature Flags and Staged Rollouts in React Native: Release Without Fear

Shipping a mobile app is not like deploying a website. Once a binary is in the stores, you cannot roll it back instantly, and users update on their own schedule. Feature flags close that gap: they let you separate deploying code from releasing behavior. This tutorial shows a practical, provider-agnostic way to add flags, remote config, and staged rollouts to a React Native app.

Why flags matter more on mobile

  • Store review latency. A bad release can live for days. A flag turns a feature off in minutes.
  • Version fragmentation. Several app versions are in the wild at once, so the backend must serve each of them safely.
  • Native-dependent features. You can ship code for a feature early and enable it only when the supporting build is widespread.

Step 1: Define a typed flag contract

Start with one file that declares every flag, its type, and a safe default. The default is what users get when the network is down on first launch.

// flags/definitions.ts
export const flagDefaults = {
  newCheckoutFlow: false,
  searchDebounceMs: 250,
  minSupportedVersion: '1.0.0',
} as const;

export type FlagKey = keyof typeof flagDefaults;
export type FlagValue<K extends FlagKey> = (typeof flagDefaults)[K];

Step 2: Build a small flag store

Keep the provider behind your own interface. Whether values come from a vendor SDK, Firebase Remote Config, or your own endpoint, screens should never import the vendor directly.

// flags/store.ts
import AsyncStorage from '@react-native-async-storage/async-storage';
import { create } from 'zustand';
import { flagDefaults, FlagKey } from './definitions';

const CACHE_KEY = 'flags:v1';

type State = {
  values: Record<string, unknown>;
  ready: boolean;
  hydrate: () => Promise<void>;
  refresh: () => Promise<void>;
};

export const useFlagStore = create<State>((set, get) => ({
  values: { ...flagDefaults },
  ready: false,
  hydrate: async () => {
    const cached = await AsyncStorage.getItem(CACHE_KEY);
    if (cached) set({ values: { ...flagDefaults, ...JSON.parse(cached) } });
    set({ ready: true });
    get().refresh(); // fire and forget; never block startup on the network
  },
  refresh: async () => {
    try {
      const res = await fetch('https://api.example.com/flags');
      if (!res.ok) return;
      const remote = await res.json();
      await AsyncStorage.setItem(CACHE_KEY, JSON.stringify(remote));
      set({ values: { ...flagDefaults, ...remote } });
    } catch {
      // keep the last known values
    }
  },
}));

export function useFlag<K extends FlagKey>(key: K) {
  return useFlagStore((s) => s.values[key]) as (typeof flagDefaults)[K];
}

The order matters: defaults, then cached values, then fresh values. The app always has an answer immediately.

Step 3: Decide when flag changes apply

A flag flipping while a user is mid-flow is a bug factory. Two rules work well:

  1. Apply on next launch or next screen mount for anything that changes layout or navigation. Read the value once into a ref when the screen mounts.
  2. Apply live only for kill switches and safe tunables, such as a debounce interval.
function CheckoutEntry() {
  const enabled = useFlag('newCheckoutFlow');
  const frozen = React.useRef(enabled).current; // stable for this visit
  return frozen ? <NewCheckout /> : <LegacyCheckout />;
}

Step 4: Target by app version

Because many versions are live, include the app version and platform in the request so the server can target safely. Never enable a flag for a version that lacks the code for it.

import * as Application from 'expo-application';
import { Platform } from 'react-native';

const query = new URLSearchParams({
  version: Application.nativeApplicationVersion ?? '0',
  platform: Platform.OS,
});
fetch(`https://api.example.com/flags?${query}`);

Use the same mechanism for a force-update gate: compare the version against minSupportedVersion and show a blocking screen if it is too old.

Step 5: Staged rollouts

Roll out by percentage using a stable bucket, so a given user stays in or out as the percentage grows. Hash a persistent anonymous ID rather than picking randomly on every launch.

function bucket(id: string): number {
  let h = 0;
  for (let i = 0; i < id.length; i++) h = (h * 31 + id.charCodeAt(i)) >>> 0;
  return h % 100;
}
const inRollout = bucket(anonId) < rolloutPercent;

A sensible ramp is internal team, then 1%, 10%, 50%, and 100%, pausing at each step to watch crash-free sessions and key funnel metrics. Tie these to the observability setup you already have so a regression in the exposed group is visible.

Step 6: Test both sides

Every flag creates two code paths. Test them both:

  • Unit test components with the store seeded to each value.
  • Keep end-to-end flows runnable with flags forced via a test-only override.
  • Record the exposed flag values as attributes on crash reports and analytics events so that you can reproduce bugs.

Step 7: Retire flags

Flags are debt. For each one, record an owner and a removal date. After a feature reaches 100% and has been stable for a release or two, delete the flag, the dead branch, and the server entry. A short quarterly audit keeps the flag file small.

Common pitfalls

  • Blocking startup on a flag fetch. Always render with cached or default values.
  • Flags that gate native code. A flag cannot add a native module that the installed binary does not contain. Gate on version.
  • Nested flag dependencies. Avoid flags whose meaning depends on other flags; collapse them into one.
  • No kill switch. Every risky feature should be wrapped in a flag from the first commit.

Wrapping up

A typed contract, a cached store, version-aware targeting, and stable percentage rollouts give you most of what a mobile team needs from feature management, with no lock-in to a provider. If your team wants help designing a release process or reviewing an existing one, the senior React Native engineers at AppReactors are happy to help. Get in touch through our contact page.