> ## Documentation Index
> Fetch the complete documentation index at: https://docs.craveup.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Deployment

> Deploy a direct Crave storefront with exact origins and no browser credentials.

## Storefront environment

| Variable                             | Required                     | Description                                                   |
| ------------------------------------ | ---------------------------- | ------------------------------------------------------------- |
| `NEXT_PUBLIC_CRAVEUP_API_URL`        | Yes                          | Public Crave API origin.                                      |
| `NEXT_PUBLIC_CRAVEUP_LOCATION_ID`    | Standalone/local quickstarts | Published location override.                                  |
| `NEXT_PUBLIC_CRAVEUP_MERCHANT_SLUG`  | Standalone/local quickstarts | Published merchant override.                                  |
| `NEXT_PUBLIC_STOREFRONT_URL`         | Optional                     | Canonical metadata override; defaults to the request host.    |
| `NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY` | For checkout                 | Browser-safe Stripe publishable key for the same environment. |
| `NEXT_PUBLIC_GOOGLE_MAPS_API_KEY`    | For delivery maps            | Browser key restricted by domain and API.                     |

In the hosted `cravejs-storefront-template`, the controlled host/subdomain
selects the merchant and the `[locationId]` route selects the location. Do not
duplicate those tenant selectors as production environment variables. The
prefixed merchant and location variables above are only for standalone or local
quickstart wiring. The canonical storefront origin is host-derived from request
headers by default; set `NEXT_PUBLIC_STOREFRONT_URL` only when deployment
metadata needs an explicit override.

Do not configure private Crave API keys, provider credentials or inbound webhook secrets, cart capabilities, customer JWTs, or receipt capabilities as public variables.

## API service environment

Provider credentials remain on the API service. Every browser deployment needs its exact browser origin registered before it sends credentials or capabilities. An origin is the scheme, hostname, and non-default port; paths are not part of an origin.

For the Crave-managed API, provide the local-development, stable-preview, and production origins to the Crave integration owner. There is currently no wildcard or arbitrary self-service bypass. Register stable preview origins individually; do not attempt to allow every generated preview hostname.

Operators of the API service configure the approved origins as a comma-separated list:

```env theme={null}
CORS_ALLOWED_ORIGINS=https://order.example.com,https://preview.example.com
```

First-party `https://*.craveup.com` origins are allowed by default. Localhost is allowed only outside production. The API accepts `Authorization`, `X-Cart-Token`, `X-Checkout-Handoff`, `X-Receipt-Token`, `Idempotency-Key`, `If-Match`, `X-Request-Id`, and `Content-Type`, and exposes `ETag` plus `X-Request-Id`. Restart or redeploy the API after changing its static allowlist, then verify the preflight from the exact deployed origin.

Native iOS and Android requests normally omit the browser `Origin` header. Expo web, embedded web views that send an origin, and browser storefronts still require exact registration.

## Vercel or Netlify

1. Import the storefront repository.
2. Add the public variables for the correct environment.
3. Add the deployed origin to the API allowlist before testing cross-origin requests.
4. Build and deploy a preview.
5. Verify anonymous catalog reads, ordering-session creation, cart mutation, PaymentIntent creation, and terminal order polling.
6. Promote the exact verified commit to production.

## Required release gates

```bash theme={null}
pnpm test
pnpm lint
pnpm check-types
pnpm build
```

Also scan generated browser assets for credentials and validate that cart/customer/receipt capabilities never appear in URLs or analytics. A healthy page load alone is not an ordering-flow verification.

## Rotation and rollback

Rotating private provider credentials does not require rebuilding the storefront. Rotating the cart capability key ring requires the API migration/runbook for active carts. Roll back API and storefront releases together only when their public contract differs; otherwise deploy the failing surface independently.