Skip to main content

Getting Started

Requirements

  • React Native 0.76+ (iOS 15.4+, Android API 26+)
  • Expo SDK 52+ (if using Expo managed workflow)
  • @react-native-async-storage/async-storage
  • react-native-device-info
  • react-native-onesignal (optional — required for push notifications)

Installation

yarn add react-native-stackfront-sdk
If you use Expo, install the required dependencies after adding the SDK:
npx expo install @react-native-async-storage/async-storage react-native-device-info react-native-onesignal

Quick Start

Wrap your app’s root component in StackfrontProvider. This initializes the SDK, fetches the remote configuration, and makes all services available through context hooks.
App.tsx
import React from 'react';
import { StackfrontProvider } from 'react-native-stackfront-sdk';
import { NavigationContainer } from '@react-navigation/native';
import { GestureHandlerRootView } from 'react-native-gesture-handler';
import { SafeAreaProvider } from 'react-native-safe-area-context';
import { StatusBar } from 'expo-status-bar';
import RootNavigator from './navigation/RootNavigator';

const SHOP_DOMAIN = 'your-shop.myshopify.com';
const DEVELOPER_API_KEY = 'sf_test_your_api_key';
const API_BASE_URL = 'https://your-stackfront-api.example.com';
const APP_VERSION = '1.0.0';

function AppContent() {
  const { ready, config } = useStackfront();

  if (!ready) {
    return null; // or a loading screen
  }

  return (
    <>
      <StatusBar style="dark" />
      <RootNavigator />
    </>
  );
}

export default function App() {
  return (
    <StackfrontProvider
      shopDomain={SHOP_DOMAIN}
      developerApiKey={DEVELOPER_API_KEY}
      apiBaseUrl={API_BASE_URL}
      appVersion={APP_VERSION}
    >
      <GestureHandlerRootView style={{ flex: 1 }}>
        <SafeAreaProvider>
          <NavigationContainer>
            <AppContent />
          </NavigationContainer>
        </SafeAreaProvider>
      </GestureHandlerRootView>
    </StackfrontProvider>
  );
}

StackfrontProvider Props

PropTypeRequiredDefaultDescription
shopDomainstringYesYour Shopify store domain (e.g. my-store.myshopify.com).
developerApiKeystringYesYour Stackfront developer API key. Get one from the dashboard.
apiBaseUrlstringNoSDK’s default APIBase URL for the Stackfront REST API.
appVersionstringNoCurrent version of your app. Included in events and device metadata.
childrenReactNodeYesYour app’s component tree.

What Happens on Init

When StackfrontProvider mounts, the SDK automatically:
  1. Fetches remote config — retrieves your storefront access token, OneSignal app ID, and feature flags from the Stackfront API.
  2. Initializes the Storefront GraphQL client — connects to Shopify’s Storefront API using the fetched token.
  3. Initializes local storage — sets up AsyncStorage for wishlist and event caching.
  4. Registers for push notifications — if OneSignal is configured, initializes the SDK and requests notification permission.
  5. Tracks the app_opened event — sends a lifecycle event to the analytics pipeline.
  6. Sets ready to true — only then does your UI render.
Access the initialized state via the useStackfront() hook:
const { ready, error, config, events, products, cart, customer } = useStackfront();

Next Steps