ContextQMD
Back to Spree

Quickstart

docs/developer/storefront/nextjs/quickstart.mdx

5.6.03.3 KB
Original Source

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:

bash
npx create-spree-app my-store

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:

bash
git clone https://github.com/spree/storefront.git
cd storefront
npm 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:

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.).

Development

bash
npm run dev

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

<Note> Testing Apple Pay / Google Pay locally needs a public HTTPS URL. See [Wallet Payments in Development](/developer/storefront/nextjs/wallet-payments). </Note>

Production Build

bash
npm run build
npm start

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