React Native SDK

Package: @signakit/flags-react-native Registry: npm Environments: React Native ≥ 0.74, Expo SDK 51+

A self-contained SDK for React Native and Expo apps. Fetches your flag config from the SignaKit CDN once on initialization, evaluates all flags locally on-device, and surfaces decisions through a context provider and a useFlag hook. No browser APIs are used — events go over fetch, and optional config persistence uses AsyncStorage rather than sessionStorage.

Installation

npm install @signakit/flags-react-native

If you want offline-tolerant cold starts, also install the optional AsyncStorage peer:

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

For Expo managed workflow, link the native module:

npx expo install @react-native-async-storage/async-storage

SignaKitProvider

Wrap your app root with SignaKitProvider. It creates the SDK client, fetches the flag config, and makes all decisions available to any useFlag call in the tree.

import { SignaKitProvider } from '@signakit/flags-react-native'
import { RootNavigator } from './navigation/RootNavigator'

export default function App() {
  return (
    <SignaKitProvider
      sdkKey="sk_prod_yourOrgId_yourProjectId_random"
      userId="user-123"
      attributes={{ plan: 'pro', country: 'US' }}
      persistConfig
      loadingFallback={<SplashScreen />}
    >
      <RootNavigator />
    </SignaKitProvider>
  )
}

Props

// ❌ New object on every render → recreates user context and re-evaluates all flags
<SignaKitProvider attributes={{ plan: user.plan }}>

// ✓ Stable reference
const attributes = useMemo(() => ({ plan: user.plan }), [user.plan])
<SignaKitProvider attributes={attributes}>

Initialization behavior

The Provider runs this sequence on mount:

1. If persistConfig is enabled, loads the last cached config from AsyncStorage immediately.
2. Fetches fresh config from the SignaKit CDN.
3. If the network request succeeds, the fresh config is used and written back to AsyncStorage (when persistConfig is enabled).
4. If the network request fails but a cached config was loaded in step 1, the Provider resolves as ready using the cached config — the app boots offline-tolerant.
5. If both fail, the Provider resolves with loading: false and all useFlag calls return the off state (fail-open).

useFlag(flagKey)

Evaluates a single flag for the current user.

import { useFlag } from '@signakit/flags-react-native'

function CheckoutButton() {
  const { enabled, variationKey, loading } = useFlag('new-checkout')

  if (loading) return <ActivityIndicator />

  return enabled ? <NewCheckoutButton /> : <LegacyCheckoutButton />
}

Return value

Variation-specific rendering

Use variationKey when you need to render different UI for each variant of an A/B test:

function HeroSection() {
  const { variationKey, loading } = useFlag('hero-redesign')

  if (loading) return <Skeleton />

  if (variationKey === 'treatment_a') return <HeroVariantA />
  if (variationKey === 'treatment_b') return <HeroVariantB />
  return <HeroControl />
}

Flag variables

Flags can carry typed variable payloads — use variables to read them:

function OnboardingFlow() {
  const { enabled, variables } = useFlag('onboarding-steps')

  if (!enabled) return <DefaultOnboarding />

  const maxSteps = variables['max_steps'] as number ?? 3
  return <OnboardingWizard steps={maxSteps} />
}

useFlagAll()

If you need to evaluate all flags at once outside of React (e.g., in a navigation guard or background task), use the client directly:

import { useUserContext } from '@signakit/flags-react-native'

function useAllDecisions() {
  const userContext = useUserContext()
  if (!userContext) return {}
  return userContext.decideAll()
}

decideAll() fires an $exposure event for every flag the user is bucketed into. Call it once, not on every render.

useTrackEvent()

import { useUserContext } from '@signakit/flags-react-native'

function PurchaseButton({ amount }: { amount: number }) {
  const userContext = useUserContext()

  const handlePress = async () => {
    await userContext?.trackEvent('purchase_completed', {
      value: amount,
      metadata: { plan: 'pro' },
    })
  }

  return <Button onPress={handlePress} title="Buy now" />
}

trackEvent accepts an event key and an optional options object:

Fire and forget — trackEvent never throws. Errors are logged to the console.

useUserContext()

Returns the active SignaKitUserContext instance, or null while the Provider is initializing. Use this when you need direct access to decide(), decideAll(), or trackEvent() outside of the useFlag hook.

import { useUserContext } from '@signakit/flags-react-native'

function FeatureGate({ flagKey, children }: { flagKey: string; children: ReactNode }) {
  const userContext = useUserContext()
  if (!userContext) return null

  const decision = userContext.decide(flagKey)
  return decision?.enabled ? <>{children}</> : null
}

AsyncStorage persistence

When persistConfig is enabled on the Provider, the SDK writes the latest successful config to AsyncStorage under the key prefix @signakit/config:. On the next cold start, this cached config is loaded immediately before the network request completes — so the app renders with real flag decisions rather than the off/loading state.

AsyncStorage keys written by the SDK:
  @signakit/config:{sdkKey}   — the serialized flag config JSON
  @signakit/etag:{sdkKey}     — the ETag of the last fetch for conditional requests

The onReady() result includes a fromCache boolean indicating whether the ready state was satisfied by the AsyncStorage cache rather than a fresh network response:

const { success, fromCache, reason } = await client.onReady()
// success: true, fromCache: true  → served from cache; network request may still be pending
// success: true, fromCache: false → fresh config fetched successfully
// success: false                  → no network and no cache available

Exposure deduplication

Unlike the browser SDK, there is no sessionStorage available in React Native. The SDK uses an in-memory Map keyed by ${flagKey}:${userId} to deduplicate $exposure events. The map lives for the lifetime of the SignaKitClient instance — it resets on app cold start, which mirrors the natural session boundary of a mobile app.

$exposure events are only fired for ab-test and multi-armed-bandit rules. Flags using targeted rules (simple rollouts) never fire an exposure event, since there is no experiment to attribute.

TypeScript types

import type {
  SignaKitClientConfig,
  OnReadyResult,
  UserAttributes,
  SignaKitDecision,
  SignaKitDecisions,
  SignaKitEvent,
  TrackEventOptions,
  VariableValue,
  FlagVariable,
  RuleType,
  Environment,
  AsyncStorageLike,
} from '@signakit/flags-react-native'

The AsyncStorageLike interface describes the minimal contract the SDK requires for persistence. Pass a custom implementation if you prefer a different storage backend:

export interface AsyncStorageLike {
  getItem(key: string): Promise<string | null>
  setItem(key: string, value: string): Promise<void>
  removeItem(key: string): Promise<void>
}

Differences from the web React SDK

Anti-patterns

Related

• React SDK →
• Flutter SDK →
• Quickstart →
• Concepts: A/B Testing →