Skip to main content

​
Storefront environment

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:
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

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.