React SDK

npm install @storeos/storefront-client react react-dom @tanstack/react-query zod immer use-immer
# optional for App Router server helpers
npm install next

"use client";

import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { StoreOSProvider } from "@storeos/storefront-client/react";

const queryClient = new QueryClient();

export function Providers({ children }: { children: React.ReactNode }) {
  return (
    <QueryClientProvider client={queryClient}>
      <StoreOSProvider
        config={{
          tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
          siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
          // apiUrl defaults to https://storefront-api.storeos.dev
        }}
      >
        {children}
      </StoreOSProvider>
    </QueryClientProvider>
  );
}

import { useAuth, useSession } from "@storeos/storefront-client/react";

function AccountMenu() {
  const { session, login, logout, loading } = useAuth();
  // or: const session = useSession();

  if (loading) return null;

  if (!session.user) {
    return (
      <button
        onClick={() =>
          login({ user: "customer@example.com", password: "••••••••" })
        }
      >
        Sign in
      </button>
    );
  }

  return (
    <div>
      <span>{session.user.name ?? session.user.email}</span>
      <button onClick={() => logout()}>Sign out</button>
    </div>
  );
}

import { useCart } from "@storeos/storefront-client/react";
import type { CartLineItem } from "@storeos/storefront-client/react";

function AddToCartButton({ item }: { item: CartLineItem }) {
  const { addItem, totalItems, subTotalAmount } = useCart();

  return (
    <button onClick={() => addItem(item)}>
      Add to cart ({totalItems}) — {subTotalAmount}
    </button>
  );
}

import { useQuery } from "@tanstack/react-query";
import { gqlClient } from "@storeos/storefront-client/react";
import { PRODUCTS_QUERY } from "@storeos/storefront-client/react/queries";

function ProductGrid() {
  const { data, isLoading } = useQuery({
    queryKey: ["products"],
    queryFn: () =>
      gqlClient<{ products: { nodes: unknown[] } }>({
        query: PRODUCTS_QUERY,
        variables: { page: 1, limit: 24 },
      }),
  });

  if (isLoading) return null;
  return /* render data.products.nodes */;
}

import { initStoreOS } from "@storeos/storefront-client/react";
import {
  getServerSession,
  gqlServerClient,
} from "@storeos/storefront-client/react/server";
import { PRODUCTS_QUERY } from "@storeos/storefront-client/react/queries";

initStoreOS({
  tenant: process.env.NEXT_PUBLIC_SITE_API_TENANT!,
  siteUrl: process.env.NEXT_PUBLIC_SITE_URL,
});

export default async function Page() {
  const session = await getServerSession();
  const data = await gqlServerClient({
    query: PRODUCTS_QUERY,
    variables: { page: 1, limit: 12 },
  });

  return /* … */;
}

import { useVariantSelection } from "@storeos/storefront-client/react";

function VariantPicker({ product }) {
  const {
    selectedAttributes,
    setSelectedAttributes,
    selectedVariant,
    isOptionAvailable,
  } = useVariantSelection({
    variants: product.variants,
    variantConfigs: product.variantConfigs,
    productId: product._id,
  });

  // Only valid combinations are stored; impossible combos are normalized away.
}

import {
  getCheckoutFormSchema,
  checkoutFormSchema,
  loggedInCheckoutFormSchema,
} from "@storeos/storefront-client/react";
import type { CheckoutFormData } from "@storeos/storefront-client/react";

const schema = getCheckoutFormSchema(isLoggedIn);
const parsed: CheckoutFormData = schema.parse(formValues);

import {
  formatCurrency,
  formatAmount,
  getFileUrl,
  createUrl,
  getSiteUrl,
  getDeliveryCharge,
  calculateOrderTotal,
  getDeliveryAreaDisplayName,
  getVariantFromSelection,
  isVariantOptionAvailable,
} from "@storeos/storefront-client/react";

import {
  ME_QUERY,
  LOGIN_MUTATION,
  PRODUCTS_QUERY,
  PRODUCT_BY_ID_QUERY,
  SEARCH_PRODUCTS_QUERY,
  COLLECTIONS_QUERY,
  CREATE_ORDER_MUTATION,
  MY_ORDERS_QUERY,
  ORDER_DETAILS_QUERY,
  CANCEL_ORDER_MUTATION,
  VERIFY_COUPON_MUTATION,
  STOREFRONT_QUERY,
} from "@storeos/storefront-client/react/queries";

import {
  DeliveryArea,
  Invoice_Payment_Method,
  Invoice_Status,
  ProductStatus,
} from "@storeos/storefront-client/react/types";