Core Concepts

Architecture

The SDK operates as a headless-first layer between your React Native app and two Shopify APIs:

Stackfront REST API — managed services (loyalty, reviews, stories, push notifications, events, billing, config). Handled by the ApiClient service.
Shopify Storefront GraphQL API — commerce primitives (products, cart, checkout, customer, orders). Handled by the StorefrontClient service.

The SDK abstracts this so your code never needs to know which API is being called.

Provider & Context

Wrap your root component in StackfrontProvider. On mount, it fetches remote config, initializes all services, and exposes them via React context. All hooks and services access this context through the useStackfront() hook:

import { useStackfront } from 'react-native-stackfront-sdk';

function MyComponent() {
  const { ready, config, products, cart, events } = useStackfront();

  if (!ready) return <Loading />;
  // ...
}

Services vs Hooks

The SDK provides two layers of API: Services — direct imperative access to underlying functionality (API calls, storage, GraphQL queries). Accessible via useStackfront(). Hooks — opinionated React wrappers over services with built-in state management (data, loading, error). Prefer hooks for most UI work.

Layer	Example	When to use
`useStackfront().products`	Service — raw API calls	Composing custom logic
`useProducts()`	Hook — reactive state	Standard UI rendering

Available Hooks (25)

Hook	Returns	Description
`useStackfront()`	Context value	Access every service, config, and lifecycle state
`useProducts()`	`Product[]`	Paginated product listing
`useProduct(handle)`	`Product \| null`	Single product by handle
`useSearch(query)`	`Product[]`	Full-text product search
`useCollections()`	`Collection[]`	Collection listing
`useCart()`	`Cart \| null`	Current cart with line mutations
`useCheckout()`	`{ url, loading }`	Checkout URL for web checkout
`useCustomer()`	`Customer \| null`	Logged-in customer profile
`useOrders()`	`Order[]`	Customer order history
`usePush()`	`{ permission, token }`	Push notification registration state
`useConfig()`	`SdkConfigResponse`	Remote SDK configuration
`useFeatureFlags()`	`FeatureFlag[]`	Remote feature flags
`useBranding()`	`BrandingConfig`	Store branding settings
`useBanners()`	`Banner[]`	Active banners
`useAnnouncements()`	`Announcement[]`	Announcement bar config
`usePopups()`	`Popup[]`	Popup/overlay config
`useStories()`	`Story[]`	Story/collection highlights
`useReviews()`	`Review[]`	Product reviews
`useSocialProof()`	`SocialProof[]`	Live social proof notifications
`useWishlist()`	`WishlistItem[]`	User’s wishlist
`useLoyalty()`	`LoyaltyData`	Points, tiers, and rewards
`useBilling()`	`BillingStatus`	App subscription/billing info
`useIntegrations()`	`Integration[]`	Third-party integration status
`useAbandonedCart()`	`{ enabled, optedIn, optIn, optOut }`	Abandoned cart notification opt-in state and controls

Available Services (15)

Service	Description
`ApiClient`	HTTP client for the Stackfront REST API
`StorefrontClient`	GraphQL client for the Shopify Storefront API
`StorageService`	AsyncStorage wrapper for local persistence
`EventService`	Event tracking and batching pipeline
`DeviceService`	Push notification device registration
`ConfigService`	Remote config fetching
`ProductService`	Product and collection GraphQL queries
`CartService`	Cart CRUD via Storefront GraphQL mutations
`CustomerService`	Customer auth, profile, and orders
`LoyaltyService`	Points, tiers, and rewards API
`ReviewService`	Product review API
`StoryService`	Story management API
`SocialProofService`	Live social proof feed API
`IntegrationService`	Third-party integration data API
`BillingService`	App subscription billing API
`WishlistService`	Local wishlist persistence

GraphQL Operations

The SDK bundles pre-written GraphQL queries and mutations for the Shopify Storefront API. These are used internally by the ProductService, CartService, and CustomerService, and are also exported directly:

import { GET_PRODUCTS, CART_CREATE, CUSTOMER_GET } from 'react-native-stackfront-sdk';

Available operations:

Operation	Type	Description
`GET_PRODUCTS`	Query	Paginated product list
`GET_PRODUCT`	Query	Single product by handle
`GET_PRODUCT_BY_ID`	Query	Single product by ID
`GET_COLLECTIONS`	Query	Paginated collection list
`GET_COLLECTION`	Query	Single collection with products
`SEARCH_PRODUCTS`	Query	Full-text product search
`CART_CREATE`	Mutation	Create a new cart
`CART_GET`	Query	Fetch cart by ID
`CART_LINES_ADD`	Mutation	Add lines to cart
`CART_LINES_UPDATE`	Mutation	Update cart line quantities
`CART_LINES_REMOVE`	Mutation	Remove lines from cart
`CART_BUYER_IDENTITY_UPDATE`	Mutation	Set customer identity on cart
`CUSTOMER_CREATE`	Mutation	Register a new customer
`CUSTOMER_ACCESS_TOKEN_CREATE`	Mutation	Log in (create access token)
`CUSTOMER_ACCESS_TOKEN_DELETE`	Mutation	Log out (delete access token)
`CUSTOMER_GET`	Query	Fetch customer profile + orders
`CUSTOMER_RECOVER`	Mutation	Password reset email
`CUSTOMER_UPDATE`	Mutation	Update customer profile

Lifecycle

App starts → StackfrontProvider mounts
Config fetched from Stackfront API (storefront token, OneSignal ID, feature flags)
Storefront GraphQL client initialized
Storage initialized (AsyncStorage)
OneSignal initialized if configured
ready = true
app_opened event tracked
App renders

Access ready and error from useStackfront() to gate your UI:

const { ready, error } = useStackfront();
if (error) return <ErrorScreen error={error} />;
if (!ready) return <SplashScreen />;
return <AppContent />;

​Core Concepts

​Architecture

​Provider & Context

​Services vs Hooks

​Available Hooks (25)

​Available Services (15)

​GraphQL Operations

​Lifecycle