Browser client & hooks

createStorekitClient() and the React hooks — useCart, useSession, usePaymentConfirmation.

@usestorekit/sdk/react is a "use client" module for the browser. It talks to your same-origin proxy (storekit.handler()), so your store key never reaches the client and the session rides along in an httpOnly cookie.

createStorekitClient()

lib/storekit-client.ts

"use client";

import { createStorekitClient } from "@usestorekit/sdk/react";

export const storefront = createStorekitClient();

Prop

Type

It returns resource namespaces (same shape as the server client), cookie-backed cart/auth facades, and the hooks below.

Hooks

useCart()

Backed by a shared store — every component using the same client stays in sync without polling. Updating the cart in one place updates the header badge everywhere.

const {
  cart,      // Cart | null
  count,     // number — total quantity
  loading,
  error,     // StorefrontError | null
  add,       // (item) => Promise<Result<Cart>>
  setQuantity, // (lineId, qty) => Promise<Result<Cart>>
  remove,    // (lineId) => Promise<Result<Cart>>
  clear,     // () => Promise<void>
  refresh,   // () => Promise<void>
} = storefront.useCart();

components/cart-badge.tsx

"use client";
import { storefront } from "@/lib/storekit-client";

export function CartBadge() {
  const { count } = storefront.useCart();
  return <span>{count}</span>;
}

useSession()

const {
  data,    // Customer | null
  loading, // true until first fetch resolves
  error,
  refresh, // () => Promise<void>
  update,  // (input) => Promise<Result<Customer>> — patches profile + syncs state
} = storefront.useSession();

useStore()

const { data, loading, error } = storefront.useStore(); // ResourceState<Store>

usePaymentConfirmation()

Drives the payment return page — confirms the order, retries transient network failures, and refreshes the cart on success.

const { status, order, message, error, retry } =
  storefront.usePaymentConfirmation(orderId);

status is "processing" | "success" | "pending" | "failed" | "error". See Payments for the full example.

Cart & auth facades (without hooks)

Need imperative calls outside a component? The same operations are available directly:

await storefront.cart.add({ variantId, quantity: 1 });
await storefront.cart.setQuantity(lineId, 2);
await storefront.cart.remove(lineId);
await storefront.cart.clear();

await storefront.auth.requestOtp(phone);
await storefront.auth.verifyOtp(phone, otp);
await storefront.auth.session();
await storefront.auth.logout();

Prefer the hooks in UI so shared state stays consistent.

formatMoney()

Exported from all three entry points. Locale-pinned by default so server and client render the same string (no hydration mismatch):

import { formatMoney } from "@usestorekit/sdk/react";

formatMoney("1200.00");                 // "₹1,200.00"
formatMoney(1200, "USD", "en-US");      // "$1,200.00"

Escape hatch

storefront.$core is the underlying framework-agnostic core client if you need a method the facade doesn't surface.

On this page