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