React Native providers and hooks for Boolean and multivariate flags. Built on the matching React v2 SDK, with AsyncStorage persistence and a native SSE transport included.
This branch targets the v2 toolchain; it does not publish packages. Upgrade Node/bootstrap producers and Native consumers together. The React SDK README covers the shared API.
npm install @reflag/react-native-sdk@2Requires React 17 or later (the modern JSX runtime) and a React version supported by your React Native app. Wrap your app with the Native provider, which supplies the platform adapters:
import { ReflagProvider } from "@reflag/react-native-sdk";
<ReflagProvider
publishableKey="{YOUR_PUBLISHABLE_KEY}"
context={{
user: { id: "user_123", name: "John Doe" },
company: { id: "company_123", plan: "pro" },
}}
>
<App />
</ReflagProvider>;Use only publishable keys in the app, never server secret keys. Native providers default live updates on, persistence to AsyncStorage, and SSE to react-native-sse with transport polling disabled. storage, eventSourceFactory, and enableLiveFlagUpdates remain configurable.
useFlag(key) returns a Boolean, with false while initializing or when missing. A positional JSON default requests a matching top-level value category:
import { Button } from "react-native";
import { useFlag, useTrack } from "@reflag/react-native-sdk";
function StartHuddleButton() {
const enabled = useFlag("huddle");
const settings = useFlag("huddle-settings", { maxParticipants: 10 });
const track = useTrack();
if (!enabled) return null;
return (
<Button
title={`Start huddle (up to ${settings.maxParticipants})`}
onPress={() => void track("Started huddle")}
/>
);
}Defaults infer widened direct-value types without generated declarations. Accepted false, zero, empty strings and null are not replaced by truthy fallbacks. Explicit null requests arbitrary JSON; undefined retains the Boolean-first behavior. Returned JSON values are independent copies. Defaults check top-level categories, not nested runtime schemas.
Reading registers root checks immediately; application usage remains separate through useTrack(). useClient().getFlags() also returns direct values, not v1 flag wrappers. useIsLoading() reports readiness separately.
Ordinary useFlag never suspends, even inside a provider with suspense enabled. Use useFlagSuspense to wait for initialization:
import { Suspense } from "react";
import { ActivityIndicator } from "react-native";
import { useFlagSuspense } from "@reflag/react-native-sdk";
function Huddles() {
const enabled = useFlagSuspense("huddle");
return enabled ? <HuddleScreen /> : null;
}
<Suspense fallback={<ActivityIndicator />}>
<Huddles />
</Suspense>;A missing flag uses its default after initialization rather than suspending forever. Provider suspense and useOptInFlags({ suspense: true }) control opt-in metadata loading, not ordinary flag reads. An object passed as useFlag's second argument is a JSON default, not loading options.
Produce the envelope on your server using Node SDK v2:
const flags = serverClient.getFlagsForBootstrap({
user: { id: "user_123" },
company: { id: "company_123" },
});Pass the complete serialized envelope to Native:
import { ReflagBootstrappedProvider } from "@reflag/react-native-sdk";
<ReflagBootstrappedProvider
publishableKey="{YOUR_PUBLISHABLE_KEY}"
flags={flags}
>
<App />
</ReflagBootstrappedProvider>;The envelope contains protocolVersion: 2, context, evaluated flags and an optional snapshot version. Legacy v1 bootstrap is rejected. Live updates require a snapshot version. Never expose secret keys or server-only attributes in bootstrap data: later refreshes use app-visible context and may differ from server evaluation. Disable live updates when later client evaluation must not replace the server result. Requesting missing opt-in metadata still makes a client-side request even with live updates disabled.
ReflagClientProvider accepts an externally initialized matching v2 client. Its lifecycle and platform-adapter configuration belong to your application; the Native convenience providers do not configure an external client.
useOptInFlags() returns metadata and loading state; useSetOptIn() changes membership. Metadata arrives with ordinary /flags/evaluated responses, or on demand after bootstrap without replacing server-derived values. User/company grants stay independent. Successful mutations confirm versioned evaluation and membership in one refresh. Check the returned Response.ok and catch rejections: confirmation can fail after membership changed remotely, and skipped calls return undefined. Failed metadata loading settles without exposing an error; use useClient().refresh() to retry.
The toolbar and built-in feedback UI are web-only and disabled by default. Use your own Native feedback UI with useSendFeedback() or client.feedback(); enabling a web UI option does not make it Native-compatible.
enableTracking: false disables checks and ordinary tracking. Offline mode skips HTTP/tracking; use direct-value fallbacks such as fallbackFlags={{ huddle: true, settings: { mode: "offline" } }}.
Native reexports React's hooks and shares React's Flags registry. Register direct-value schemas in @reflag/react-sdk, not a separate Native registry:
import "@reflag/react-native-sdk";
declare module "@reflag/react-sdk" {
interface Flags {
huddle: boolean;
"huddle-settings": { maxParticipants: number };
}
}Registration constrains keys and checks non-null positional defaults, including required and nested fields. Named-interface and readonly defaults work. It does not restore wrappers or validate nested runtime payloads. The Native package reexports the same registry/types; v2 CLI React-format declarations target this shared interface. Regenerate legacy wrapper declarations before use; CLI v2 is a separate release dependency.
import { useEffect, useRef } from "react";
import { AppState } from "react-native";
import { useClient } from "@reflag/react-native-sdk";
function AppStateListener() {
const client = useClient();
const appState = useRef(AppState.currentState);
useEffect(() => {
const subscription = AppState.addEventListener("change", (nextState) => {
if (
appState.current.match(/inactive|background/) &&
nextState === "active"
) {
void client.refresh();
}
appState.current = nextState;
});
return () => subscription.remove();
}, [client]);
return null;
}Mount this listener under a Native provider. Context prop changes and useUpdateUser/useUpdateCompany/useUpdateOtherContext also update evaluation context.
- Replace
const { isEnabled, track } = useFlag(key)withconst enabled = useFlag(key)and a separateuseTrack()call. - Replace remote-config wrappers with authored multivariate flags and positional JSON defaults.
- Use
useFlagSuspense, notuseFlag(key, { suspense: true }), for readiness-waiting reads. - Use direct-value fallback maps for multivariate flags; Boolean string-array shorthand remains supported. Migrate both ends of bootstrap to protocol v2.
- Rebuild against matching Native/React/Browser v2 packages and regenerate legacy declarations.
The Expo and bare React Native examples use the v2 Native APIs. OpenFeature providers are separate integrations and do not gain v2 support from this migration.