spree-headless-storefront

name	spree-headless-storefront
description	Build with Spree's headless Next.js storefront — the official `spree/storefront` repo (Next.js 16 App Router with Server Actions and Turbopack, React 19 Server Components, Tailwind CSS 4, TypeScript 5, `@spree/sdk`, Sentry), server-only auth (httpOnly JWT cookies + publishable key), MeiliSearch faceted catalog, one-page checkout with Apple/Google Pay/Klarna/Affirm/SEPA, multi-region market routing, GA4 + JSON-LD SEO, and Vercel/Docker deployment. Use when forking or customizing the storefront, or evaluating headless adoption.
allowed-tools	Read, Write, Edit, Bash, Grep, Glob, WebSearch, WebFetch

Spree Headless Next.js Storefront

Before writing code

Fetch live docs:

1. Fetch https://github.com/spree/storefront (README) for current setup and customization.
2. Fetch https://spreecommerce.org/docs/developer/storefront/nextjs/quickstart for the quickstart.
3. Fetch the Next.js 16 docs for App Router / Server Actions patterns the storefront uses.
4. Cross-reference https://github.com/spree/sdk for SDK usage.
5. Check the v5.4 announcement for the storefront's release context.

Conceptual Architecture

The Two Repos

Repo	Role
spree/spree-starter	Rails backend application
spree/storefront	Next.js headless storefront

The storefront talks to the backend exclusively over API v3 (Store API).

Tech Stack

Layer	Tech
Framework	Next.js 16 (App Router, Server Actions, Turbopack)
UI runtime	React 19 (Server Components + Client Components)
Styling	Tailwind CSS 4
Type system	TypeScript 5
API client	@spree/sdk with Zod schemas
Search	MeiliSearch faceted search
Auth	Server-only — httpOnly JWT cookies + publishable key
Payments	Stripe Elements / Apple Pay / Google Pay / Link / Klarna / Affirm / SEPA
Analytics	GA4, JSON-LD, OpenGraph
Error tracking	Sentry
Deploy	Vercel (recommended) or Docker

Prerequisites

• Node 20+
• Spree backend on 5.4+ (API v3 required)
• A publishable key (pk_…) from admin

Project Layout

storefront/
├── app/
│   ├── (storefront)/      # public pages (App Router groups)
│   │   ├── [region]/[locale]/
│   │   │   ├── products/
│   │   │   ├── cart/
│   │   │   └── checkout/
│   │   └── account/
│   ├── api/                # Route Handlers for webhooks etc.
│   ├── layout.tsx
│   └── page.tsx
├── components/
│   ├── ui/                 # Tailwind-styled primitives
│   ├── product/
│   ├── cart/
│   └── checkout/
├── lib/
│   ├── spree.server.ts     # admin/auth client — never imported client-side
│   ├── spree.public.ts     # publishable-key client
│   ├── auth.ts             # Server Action helpers for sign in/out
│   └── meilisearch.ts
├── public/
├── tailwind.config.ts
├── next.config.ts
└── package.json

Auth: Server-Only by Design

• The publishable key (pk_…) is the only Spree credential that may reach the browser.
• User JWTs live in httpOnly cookies set via Server Actions; never accessible to client JS.
• The admin API key never leaves the server bundle. The storefront should never have it set in env.
• Cart order_token also in httpOnly cookie.

// app/api/auth/sign-in/route.ts (Route Handler)
import { cookies } from 'next/headers';
import { spreePublic } from '@/lib/spree.public';

export async function POST(req: Request) {
  const { email, password } = await req.json();
  const { access_token, refresh_token, expires_in } = await spreePublic.auth.signIn({ email, password });
  cookies().set('spree_jwt', access_token, {
    httpOnly: true,
    secure: true,
    sameSite: 'lax',
    maxAge: expires_in,
  });
  cookies().set('spree_refresh', refresh_token, { httpOnly: true, secure: true, sameSite: 'lax' });
  return Response.json({ ok: true });
}

Market / Region Routing

URLs follow /[region]/[locale]/...:

• /us/en/products/classic-tee
• /de/de/produkte/classic-tee

The storefront resolves current_market from the URL, then passes it to the API so backend filters by market-allowed payment methods, shipping methods, prices.

Faceted Catalog via MeiliSearch

The storefront's PLP (Product Listing Page) issues a MeiliSearch query (or hits a Spree API v3 endpoint that proxies to MeiliSearch — verify the live pattern). Facets: brand, color, size, price range, taxon. Typo-tolerant.

Checkout Flow

1. Cart page — line items, totals, suggested upsells
2. Address page — bill/ship; pre-filled for logged-in users
3. Delivery page — pick shipping method (one per shipment)
4. Payment page — pick payment method, render gateway UI
   • Stripe → Stripe Elements / Apple Pay / Google Pay / Link
   • Klarna, Affirm, SEPA — Stripe-backed
5. Review page — final totals, place order
6. Confirmation — redirect to order page with ord_…

Implemented as one-page with progressive disclosure in the official storefront.

Server Actions for Mutating Calls

// app/(storefront)/cart/actions.ts
'use server';

import { cookies } from 'next/headers';
import { revalidatePath } from 'next/cache';
import { spreePublic } from '@/lib/spree.public';

export async function addToCart(variantId: string, quantity = 1) {
  const orderToken = cookies().get('spree_cart_token')?.value;
  const result = await spreePublic.cart.addItem({ variantId, quantity, orderToken });
  if (!orderToken) {
    cookies().set('spree_cart_token', result.token, { httpOnly: true, secure: true, sameSite: 'lax' });
  }
  revalidatePath('/cart');
  return result;
}

SEO

• JSON-LD for Product, BreadcrumbList, Offer, Organization
• OpenGraph + Twitter Cards
• Sitemap generated by next-sitemap or similar
• robots.txt
• Translated meta tags per locale
• Canonical URLs respecting the region/locale prefix

Analytics

• GA4 loaded server-side via next/script
• E-commerce events: view_item, add_to_cart, begin_checkout, purchase — fired client-side after Server Action completion
• JSON-LD + Schema.org for structured data

Implementation Guidance

Cloning and Running

git clone https://github.com/spree/storefront my-storefront
cd my-storefront
cp .env.example .env.local
# Set:
#   SPREE_API_URL=http://localhost:4000   (your Spree backend)
#   NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY=pk_test_...
#   MEILISEARCH_HOST=http://localhost:7700
#   MEILISEARCH_PUBLIC_KEY=...
npm install
npm run dev  # http://localhost:3000

Customizing Pages

The App Router structure makes customization file-system-based — add or replace files under app/. For shared layout changes, edit the relevant layout.tsx.

Customizing Components

Override Tailwind tokens in tailwind.config.ts:

export default {
  theme: {
    extend: {
      colors: {
        brand: { 500: '#0066ff', 600: '#0052cc' }
      },
      fontFamily: {
        display: ['"Inter Display"', 'sans-serif']
      }
    }
  }
}

For Tailwind 4 specifically, prefer the @theme directive in CSS:

@import 'tailwindcss';

@theme {
  --color-brand-500: oklch(0.6 0.2 250);
  --font-display: 'Inter Display', sans-serif;
}

Adding a New Page

// app/(storefront)/[region]/[locale]/about/page.tsx
export default async function AboutPage({ params }: { params: Promise<{ region: string; locale: string }> }) {
  const { locale } = await params;
  return <main>About {locale}</main>;
}

Next.js 16 wraps params in a Promise — await it.

Hooking Custom Backend Data

If you've added a Metafield or extension field on the backend:

const product = await spreePublic.products.find('prod_...', { expand: ['metafields'] });
const launchDate = product.metafields?.my_app?.launch_date;

Augment SDK types via types/spree.d.ts if you want type safety.

Caching Strategy

Page	Strategy
Homepage	ISR — revalidate: 60
Product detail	ISR — revalidate: 300 (5 min)
Cart	Dynamic — dynamic = 'force-dynamic'
Account	Dynamic
Order confirmation	Dynamic

Deployment

Vercel (recommended):

• Hook the GitHub repo
• Set env vars (SPREE_API_URL, NEXT_PUBLIC_SPREE_PUBLISHABLE_KEY, MeiliSearch creds, Sentry DSN)
• Build command: npm run build
• Output: standalone

Docker:

• The repo ships a Dockerfile
• Multi-stage build to reduce image size
• Deploy to any container runtime

Common Pitfalls

• Importing spree.server.ts from a Client Component — Next.js's 'use server' enforcement is essential; opt into it.
• Storing tokens in localStorage — XSS-vulnerable; use httpOnly cookies via Server Actions.
• Hardcoding region/locale — breaks multi-market deployments.
• Forgetting revalidatePath after Server Actions — stale UI.
• MeiliSearch index drift — backend reindexes async; staging vs prod can disagree.
• Hardcoding payment-method visibility in UI — let the backend's Market config drive it.
• Bundling Sentry on the client with the server DSN — leaks credentials. Use the public DSN.
• Pinning Next.js too aggressively — the storefront repo bumps Next.js minor versions; match the storefront's pin.

Always re-fetch the storefront repo's README before customizing — the codebase iterates rapidly with each Spree release.