Skip to main content
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

  • Next.js 16 - App Router, Server Actions, Turbopack
  • React 19 - Server Components
  • Tailwind CSS 4 - Utility-first styling
  • TypeScript 5 - Full type safety
  • @spree/sdk - Official Spree Commerce SDK
  • Sentry - Error tracking and performance monitoring

​
Features

  • 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

​
Prerequisites

  • Node.js 20+
  • A running Spree Commerce 5.4+ instance

​
Installation

The fastest way to get a full project — Spree backend, this Next.js storefront, and the spree CLI, wired together — is create-spree-app:
The storefront is included by default (pass --no-storefront to skip it). It’s scaffolded into apps/storefront/ with its .env.local already pointing at the backend, so it boots against real data with no manual key wiring.

​
Standalone

To run the storefront on its own — against an existing Spree backend, or to work on the storefront repo directly — clone it and install:
Then follow Configuration to point it at your Spree API. If you plan to customize and track upstream changes, fork first.

​
Configuration

Copy the environment file:
Update .env.local with your Spree API credentials:
These are server-side only variables — no NEXT_PUBLIC_ prefix needed since all API calls happen in Server Actions.
See Deployment for all optional environment variables (Sentry, GTM, etc.).

​
Development

Open http://localhost:3001 in your browser.
Testing Apple Pay / Google Pay locally needs a public HTTPS URL. See Wallet Payments in Development.

​
Production Build

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