Next.js Quickstart

This quickstart connects a Next.js App Router project directly to the public Storefront API. No BFF or browser API key is required.

Prerequisites

Node.js 20+
A published merchant slug and location ID
The exact browser origin for local, preview, and production deployments registered with Crave
A Stripe publishable key when you add checkout

1. Create the app and install the SDK

npx create-next-app@latest my-storefront --typescript --app --tailwind
cd my-storefront
pnpm add --save-exact @craveup/storefront-sdk@2.0.1

2. Configure the public origin

Create a .env.local file with public configuration only:

NEXT_PUBLIC_CRAVEUP_API_URL=https://api.craveup.com
NEXT_PUBLIC_CRAVEUP_LOCATION_ID=loc_your_location_id
NEXT_PUBLIC_CRAVEUP_MERCHANT_SLUG=your-restaurant-slug
# Optional metadata override; the hosted template derives its origin from the request host.
# NEXT_PUBLIC_STOREFRONT_URL=https://order.example.com
NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY=pk_live_your_publishable_key

Variable	Description
`NEXT_PUBLIC_CRAVEUP_API_URL`	Crave API origin. Use the sandbox origin outside production.
`NEXT_PUBLIC_CRAVEUP_LOCATION_ID`	Standalone/local quickstart location override.
`NEXT_PUBLIC_CRAVEUP_MERCHANT_SLUG`	Standalone/local merchant override for lookup and customer login.
`NEXT_PUBLIC_STOREFRONT_URL`	Optional canonical metadata override; otherwise derived from request headers/host.
`NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY`	Browser-safe Stripe publishable key.

The hosted cravejs-storefront-template does not duplicate tenant selection in production environment variables. It derives the merchant from the controlled storefront host/subdomain and the location from the [locationId] route. Keep the prefixed merchant and location variables only for a standalone quickstart or local override. The hosted template also derives its canonical origin from the request host; set NEXT_PUBLIC_STOREFRONT_URL only when an explicit metadata override is required.

Do not put Crave private API keys, Stripe secret keys, provider credentials, cart capabilities, customer JWTs, or receipt capabilities in public environment variables.

The SDK requires an explicit baseUrl; it never derives an origin from a credential.

3. Create the browser client and scoped stores

"use client";

import type {
  StorefrontCartSession,
  StorefrontSessionStore,
} from "@craveup/storefront-sdk";
import { createStorefrontClient } from "@craveup/storefront-sdk";

const apiUrl = process.env.NEXT_PUBLIC_CRAVEUP_API_URL;
const merchantSlug = process.env.NEXT_PUBLIC_CRAVEUP_MERCHANT_SLUG;
if (!apiUrl || !merchantSlug) throw new Error("Missing Storefront configuration");

const apiOrigin = new URL(apiUrl).origin;
const storageKeyPart = (value: string) =>
  encodeURIComponent(value).replaceAll(".", "%2E");
const environmentNamespace = storageKeyPart(apiOrigin);
const scope = `${environmentNamespace}.${storageKeyPart(merchantSlug)}`;
const key = (kind: "cart" | "customer" | "receipt", resourceId: string) =>
  `storefront.${kind}.v1.${scope}.${storageKeyPart(resourceId)}`;
const cartKey = (locationId: string) => key("cart", locationId);
const customerKey = key("customer", "jwt");
const receiptKey = (receiptId: string) => key("receipt", receiptId);

function readCartSession(locationId: string): StorefrontCartSession | null {
  const storageKey = cartKey(locationId);
  const raw = sessionStorage.getItem(storageKey);
  if (!raw) return null;

  try {
    const value = JSON.parse(raw) as Partial<StorefrontCartSession>;
    if (
      value.locationId !== locationId ||
      typeof value.cartId !== "string" ||
      typeof value.revision !== "number" ||
      !Number.isInteger(value.revision) ||
      value.revision < 0 ||
      (value.accessToken !== undefined && typeof value.accessToken !== "string")
    ) {
      throw new Error("Invalid cart session");
    }
    return value as StorefrontCartSession;
  } catch {
    sessionStorage.removeItem(storageKey);
    return null;
  }
}

export const sessionStore: StorefrontSessionStore = {
  get(locationId) {
    return readCartSession(locationId);
  },
  set(session) {
    sessionStorage.setItem(cartKey(session.locationId), JSON.stringify(session));
  },
  clear(locationId) {
    sessionStorage.removeItem(cartKey(locationId));
  },
};

export const customerTokenStore = {
  get: () => sessionStorage.getItem(customerKey),
  set: (token: string) => sessionStorage.setItem(customerKey, token),
  clear: () => sessionStorage.removeItem(customerKey),
};

export const receiptTokenStore = {
  get: (receiptId: string) => sessionStorage.getItem(receiptKey(receiptId)),
  set: (receiptId: string, token: string) =>
    sessionStorage.setItem(receiptKey(receiptId), token),
  clear: (receiptId: string) =>
    sessionStorage.removeItem(receiptKey(receiptId)),
};

export const storefront = createStorefrontClient({
  baseUrl: apiOrigin,
  sessionStore,
  getAuthToken: customerTokenStore.get,
});

The environment, merchant, and location scopes prevent a staging token or one merchant’s token from being reused by another storefront. Persist the JWT returned by customer.verifyOtp with customerTokenStore.set(token). Capture a receipt capability from the URL fragment, remove the fragment immediately, and keep it with receiptTokenStore.set(receiptId, token) only while the receipt is needed.

4. Create a separate server client

import { createStorefrontClient } from "@craveup/storefront-sdk";

export const storefrontServer = createStorefrontClient({
  baseUrl: process.env.NEXT_PUBLIC_CRAVEUP_API_URL!,
});

Use the server client only for anonymous published merchant, location, menu, product, distance, order-time, and gratuity calls. It deliberately has no sessionStore or getAuthToken. Never import the browser client into a Server Component, Route Handler, or Server Action.

5. Start a cart and mutate it

"use client";

import { useEffect, useState } from "react";
import type { StorefrontCart } from "@craveup/storefront-sdk";
import { storefront } from "@/lib/storefront-browser";

const locationId = process.env.NEXT_PUBLIC_CRAVEUP_LOCATION_ID!;

export default function OrderPage() {
  const [cart, setCart] = useState<StorefrontCart | null>(null);

  useEffect(() => {
    void storefront.orderingSessions
      .start(locationId, { fulfillmentMethod: "takeout" })
      .then(({ cart }) => setCart(cart));
  }, []);

  async function addItem(productId: string) {
    if (!cart) return;
    setCart(
      await storefront.cart.addItem(locationId, cart.id, {
        productId,
        quantity: 1,
        selections: [],
        itemUnavailableAction: "remove_item",
      }),
    );
  }

  return (
    <main>
      <button onClick={() => addItem("prod_margherita")}>Add item</button>
      <p>{cart ? `${cart.totalQuantity} items` : "Starting cart…"}</p>
    </main>
  );
}

The SDK stores the returned cart capability, sends it only in a header, updates the saved revision from ETag, and generates idempotency keys. A CART_CONFLICT is surfaced to your UI; reload the cart before asking the shopper to retry. Clear the guest capability after claim, deletion, expiry, or terminal checkout handling; clear the customer JWT on logout and receipt capabilities after terminal display.

6. Complete checkout safely

For a signed-in shopper who still has a guest-capability cart, opt into the customer context when discount validation or provider customer association needs it:

const paymentSession = await storefront.checkout.createPaymentSession(
  locationId,
  cart.id,
  { includeCustomerContext: true },
);

Omit includeCustomerContext for a guest checkout. A claimed cart already uses the customer JWT because its guest capability has been cleared. Confirm the Render the payment provider named by the returned session, then poll storefront.checkout.getOrderResult(locationId, cart.id). Handle all four states: payment_pending, order_pending, completed, and failed. Clear the cart session only after terminal handling.

7. Register every browser origin

Register the exact origin for local development, each stable preview, and production before testing browser calls. An origin includes the scheme, hostname, and any non-default port. Do not request a wildcard and do not send a cart capability or customer JWT while working around a CORS failure. See Deployment.

Next steps

Manage Cart

Add fulfillment, discounts, gratuity, and conflict handling.

Checkout Flow

Confirm payment and poll the authoritative order result.

Storefront SDK

Review the complete typed client surface.

Deployment

Configure exact origins and production environment variables.

Platform

Getting Started

Quickstarts

Implementation

AI

Ordering Flow

More Guides

Integrations

Reference

Prerequisites

1. Create the app and install the SDK

2. Configure the public origin

3. Create the browser client and scoped stores

4. Create a separate server client

5. Start a cart and mutate it

6. Complete checkout safely

7. Register every browser origin

Next steps

Manage Cart

Checkout Flow

Storefront SDK

Deployment

​Prerequisites

​1. Create the app and install the SDK

​2. Configure the public origin

​3. Create the browser client and scoped stores

​4. Create a separate server client

​5. Start a cart and mutate it

​6. Complete checkout safely

​7. Register every browser origin

​Next steps

Manage Cart

Checkout Flow

Storefront SDK

Deployment

Prerequisites

1. Create the app and install the SDK

2. Configure the public origin

3. Create the browser client and scoped stores

4. Create a separate server client

5. Start a cart and mutate it

6. Complete checkout safely

7. Register every browser origin

Next steps