A production-ready, headless ecommerce storefront for Spree Commerce, built with Next.js 16, React 19, and the Spree REST API. Open source (MIT) and free to customize.
Live Demo | Quickstart Docs | TypeScript SDK
TypeScript SDK. @spree/sdk is an official typed client for every Store API endpoint (OpenAPI 3.0 documented). Autocomplete and type safety in your editor, no codegen step to maintain.
DTC and B2B out of the box run both DTC and B2B (wholesale portal) from a single instance powered by Spree Channels, with exclusive customer group pricing and product gating.
Multi-region out of the box. Country, currency, and language switching via URL segments (/us/en/, /de/de/, /uk/en/), powered by Spree Markets. Distinct selling regions bundling geography, currency, and locale in a single store.
One-page checkout. Guest and authenticated users, multi-shipment, coupon codes, gift cards, and store credit. Stripe, PayPal, and Adyen via Payment Sessions. Card data never touches your server. Swap providers easily.
Transactional emails. Order confirmation, shipping notification, password reset. Built with react-email, sent via Resend, triggered by Spree webhooks.
MIT licensed. Open source and free to use.
The live demo at demo.spreecommerce.org scores 98/100 on desktop and 88/100 on mobile for Performance on Google's Lighthouse audit, with five language versions served from the same deployment.
| Lighthouse metric | Mobile | Desktop |
|---|---|---|
| Performance | 88 | 98 |
| Accessibility | 100 | 100 |
| Best Practices | 100 | 100 |
| SEO | 100 | 100 |
No external performance plugins. No edge-side rendering hacks. The architecture is Next.js 16 App Router with React 19 Server Components, server-side data fetching via @spree/sdk, and Tailwind CSS 4.
Run the audit yourself on PageSpeed Insights
| Feature | Details |
|---|---|
| Product Catalog | Browse, search, filter products by categories, and use faceted navigation. Optional Meilisearch integration available |
| Product Details | View product information with variant selection and media |
| Shopping Cart | Add, update, and remove items with server-side state |
| One-page Checkout | Guest visitors and signed-in users supported, multi-shipments supported natively, Coupon Codes, Gift Cards, Store Credit |
| Stripe/Adyen/PayPal payments | native Stripe/Adyen/Paypal payment support with their SDKs, PCI-Compliant, 3DS-Secure, use Credit Cards, Apple Pay, Google Pay, Klarna, Affirm, SEPA payments |
| Customer Account | Full account management: Profile management, Order history with detailed order view, Address book (create, edit, delete), Gift Cards and Store Credit, Saved payment methods |
| Wholesale portal | Storefront gating, per-customer pricing and product availability, account approval workflows |
| Multi-Region Support | Country, currency, and language switching via URL segments, powered by Spree Markets |
| Responsive Design | Mobile-first Tailwind CSS styling |
| Google Tag Manager and Google Analytics 4 Ecommerce events | tracking supported natively |
| Store Policies | Policy pages fetched from Spree API, with consent checkboxes on registration and guest checkout |
| SEO-ready | meta tags, JSON-LD, OpenGraph — all built in |
| Error Tracking | Sentry integration for both server-side and client-side error monitoring with source maps |
| Technology | Role |
|---|---|
| Next.js 16 | App Router, Server Actions, Turbopack |
| React 19 | Latest React with improved Server Components |
| Tailwind CSS 4 | Utility-first styling |
| TypeScript | Full type safety |
| Sentry | Error tracking and performance monitoring with source maps |
| @spree/sdk | Official Spree Commerce SDK |
This starter follows a server-first pattern:
- Server-First Architecture - All API calls happen server-side using Next.js Server Actions
- httpOnly Cookies - Auth tokens and cart tokens are stored securely
- No Client-Side API Calls - The Spree API key is never exposed to the browser
- Cache Revalidation - Uses Next.js cache tags for efficient updates
Browser → Server Action → @spree/sdk → Spree API
(with httpOnly cookies via src/lib/spree helpers)
Project structure, the src/lib/data/ server actions, and the JWT-in-httpOnly-cookie auth flow are covered in the Architecture guide.
- Node.js 20+ (required for Next.js 16)
- A running Spree Commerce 5.4+
Recommended — scaffold a full project. create-spree-app sets up a Spree backend, this storefront, and the spree CLI together, with the storefront's environment wired to the backend automatically:
npx create-spree-app my-storeThe storefront lands in apps/storefront/.
Standalone. To run the storefront on its own against an existing Spree backend, or to work on this repo directly
-
Install dependencies:
pnpm install
-
Copy the environment file and configure:
cp .env.local.example .env.local
-
Update
.env.localwith your Spree API credentials: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).
These two are all you need to boot. Optional variables cover analytics, error tracking, the wholesale portal, transactional emails, and SEO — see the Environment Variables reference, or copy .env.example, which lists them all with inline comments.
pnpm run devOpen http://localhost:3001 in your browser.
Testing Apple Pay / Google Pay locally needs a public HTTPS URL (Stripe verifies the payment method domain from the internet). See Wallet Payments in Development for the Cloudflare Tunnel setup.
pnpm run build
pnpm startUnit and integration tests run through Vitest (pnpm test); end-to-end tests run through Playwright against a real Spree backend in Docker (pnpm run e2e:up && pnpm run test:e2e). See the Testing guide for the full E2E setup, Stripe test keys, CI, and running against your own backend.
Multiple countries, currencies, and languages from one deployment via /{country}/{locale} URL segments and edge middleware. See the Multi-Region guide.
The storefront ships in your project — restyle with Tailwind CSS, swap components in src/components/, and adjust the server actions in src/lib/data/. See the Customization guide.
The storefront can render and send its own order, shipment, and account emails with react-email and Resend, driven by Spree webhooks. See the Transactional Emails guide.
Deploy to Vercel, Docker (a multi-stage Dockerfile ships at the repo root), or any Node.js host. See the Deployment guide.
MIT