React Native SDK

Client-side SDK for React Native apps.

Overview

The React Native SDK exposes a singleton read/write model with AsyncStorage compatibility.

Get started

Understand version compatibility

Use this package in modern React Native projects with AsyncStorage installed.

Install the SDK

$Terminal

npm install react-native-featureflags @react-native-async-storage/async-storage

Initialize the client and login a context

TSTypeScript

import { useEffect } from "react";
import Flags from "react-native-featureflags";
 
export default function App() {
  useEffect(() => {
    void Flags.configure({
      apiKey: process.env.EXPO_PUBLIC_TRUFLAG_CLIENT_KEY!,
      user: { id: "anon-session" },
    });
  }, []);
 
  return <RootNavigator />;
}

TSTypeScript

import Flags from "react-native-featureflags";
 
await Flags.login({
  id: "user-123",
  attributes: {
    plan: "pro",
    country: "US",
  },
});

Access flag values

Always pass a meaningful fallback. It is used before SDK state is ready and when the key is missing.

TSTypeScript

import Flags, { useFlag, useFlagsReady } from "react-native-featureflags";
 
export function HomeScreen() {
  const ready = useFlagsReady();
  const enabled = useFlag("new-checkout-experience", false);
 
  if (!ready) return <Loading />;
  return enabled ? <CheckoutV2 /> : <CheckoutV1 />;
}
 
const welcomeCopy = Flags.getFlag("welcome-copy", "default");

Supported features

TTEXT

Available:
- configure, login, setAttributes, refresh, logout, destroy
- useFlagsReady, useFlag, useFlagPayload
- getFlag, getFlagPayload, getAllFlags
- track, notifyFlagRead
 
Not in this package:
- Migration provider/hook surface (use the LD migration SDK if you need import-compatible APIs)

Data collection

Flag reads emit exposures automatically. Use Flags.track() for custom events. Truflag automatically tracks Flag read events (i.e., getFlag or useFlag).

TSTypeScript

import Flags from "react-native-featureflags";
 
await Flags.track("checkout_completed", {
  source: "mobile",
  value: 1,
});

Background fetch

Trigger a refresh when the app returns to foreground if you want an explicit fetch point.

TSTypeScript

import { AppState } from "react-native";
import Flags from "react-native-featureflags";
 
const sub = AppState.addEventListener("change", (state) => {
  if (state === "active") {
    void Flags.refresh();
  }
});
 
// Later
sub.remove();

Shut down the client

Call Flags.destroy() during teardown flows.

TSTypeScript

import Flags from "react-native-featureflags";
 
Flags.destroy();

Troubleshooting

Network error

Verify the public key, relay URL reachability, and request timeout settings.

Storage error

Confirm @react-native-async-storage/async-storage is installed and linked correctly.