Quickstart - Spree — ContextQMD

The Spree Storefront is a production-ready, headless e-commerce storefront built with Next.js 16, React 19, and the Spree Commerce API v3.

Tech Stack

Server-First Architecture - All API calls happen server-side, API keys never exposed to the browser
Secure Authentication - JWT tokens stored in httpOnly cookies
Product Catalog - Browse, search, and filter with faceted navigation
Shopping Cart - Server-side state management
Multi-Step Checkout - Guest and signed-in users, multi-fulfillment, coupon codes, gift cards, store credit
Stripe Payments - Credit Cards, Apple Pay, Google Pay, Klarna, Affirm, SEPA and more via Spree Stripe
Google Tag Manager and GA4 Ecommerce event tracking
Customer Account - Profile, order history, address book, gift cards, saved payment methods
Multi-Region - Country and currency switching via URL segments
Responsive Design - Mobile-first Tailwind CSS

Fork the repository on GitHub, then clone your fork:

bash

git clone https://github.com/YOUR_USERNAME/storefront.git
cd storefront
npm install

This gives you a full copy you can customize freely while still being able to pull upstream updates.

bash

git clone https://github.com/spree/storefront.git
cd storefront
npm install

Copy the environment file:

bash

cp .env.local.example .env.local

Update .env.local with your Spree API credentials:

env

SPREE_API_URL=http://localhost:3000
SPREE_PUBLISHABLE_KEY=your_publishable_api_key_here

<Note> These are server-side only variables — no `NEXT_PUBLIC_` prefix needed since all API calls happen in Server Actions. </Note>

See Deployment for all optional environment variables (Sentry, GTM, etc.).

bash

npm run dev

Open http://localhost:3001 in your browser.

bash

npm run build
npm start

See the Deployment guide for Vercel, Docker, and other hosting options.