Skip to main content

​
Forking the Starter

The recommended approach is to fork the repository so you can customize freely while pulling upstream updates.

​
1. Fork on GitHub

Go to github.com/spree/storefront and click Fork.

​
2. Clone Your Fork

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

​
3. Add Upstream Remote

git remote add upstream https://github.com/spree/storefront.git

​
4. Pull Upstream Updates

When the official starter gets updates, pull them into your fork: 
git fetch upstream
git merge upstream/main
Resolve any conflicts in your customized files, then commit.

​
Styling

The storefront uses Tailwind CSS 4, which replaces the traditional tailwind.config.ts with CSS-native configuration via the @theme directive in src/app/globals.css.

​
Theme Customization

Edit the @theme inline block in src/app/globals.css to change colors, fonts, and other design tokens: 
@import "tailwindcss";

:root {
  --background: #fcfaf7;
  --foreground: #171717;
}

@theme inline {
  --color-background: var(--background);
  --color-foreground: var(--foreground);
  --font-sans: var(--font-geist);

  /* Replace with your brand colors */
  --color-primary-50: #eff6ff;
  --color-primary-100: #dbeafe;
  --color-primary-200: #bfdbfe;
  --color-primary-300: #93c5fd;
  --color-primary-400: #60a5fa;
  --color-primary-500: #0077ff;
  --color-primary-600: #0066dd;
  --color-primary-700: #0055bb;
  --color-primary-800: #004499;
  --color-primary-900: #003377;
  --color-primary-950: #001d4d;
}
Variables defined in @theme inline become Tailwind utilities automatically — for example, --color-primary-500 maps to bg-primary-500, text-primary-500, etc.

​
Components

All components live in src/components/ and can be customized or replaced: 
src/components/
├── cart/            # CartDrawer
├── checkout/        # AddressStep, DeliveryStep, PaymentStep, StripePaymentForm, etc.
├── layout/          # Header, Footer, CountrySwitcher
├── navigation/      # Breadcrumbs
├── products/        # ProductCard, ProductGrid, ProductCarousel, Filters, MediaGallery, VariantPicker
└── search/          # SearchBar
Components use standard React patterns — modify them directly or replace them entirely with your own implementations.

​
Data Layer

To customize API behavior, modify the server actions in src/lib/data/. Each file handles a specific domain:
FilePurpose
products.tsProduct listing and detail queries
cart.tsCart operations (add, update, remove)
checkout.tsCheckout flow (addresses, shipping, completion)
customer.tsAuthentication and profile management
addresses.tsAddress CRUD
orders.tsOrder history
payment.tsPayment sessions and processing
categories.tsCategories
countries.tsCountry and region data
cookies.tsAuth check helper
store.tsStore configuration
credit-cards.tsSaved payment methods
gift-cards.tsGift card management
utils.tsShared helpers (error handling, fallbacks)
These server actions call @spree/sdk directly, using helpers in src/lib/spree/ for auth cookies and locale resolution. You can add custom logic, caching strategies, or additional transformations as needed.

​
Adding New Pages

Follow the existing App Router pattern with localized routes. Place pages under the (storefront) route group to inherit the shared header/footer layout: 
src/app/[country]/[locale]/(storefront)/your-new-page/page.tsx

import { getProducts } from '@/lib/data/products';

export default async function YourNewPage() {
  const products = await getProducts({ limit: 6 });

  return (
    <div>
      <h1>Your New Page</h1>
      {/* Your content */}
    </div>
  );
}

​
Transactional Emails

Customer-facing emails are rendered in the storefront using react-email and sent via Resend. The Spree backend delivers order/shipment/password events to the storefront via webhooks.

​
Templates

Email templates are React components in src/lib/emails/:
FileEventDescription
order-confirmation.tsxorder.completedItems, totals, addresses, delivery method
order-canceled.tsxorder.canceledCancellation notice with items
shipment-shipped.tsxorder.shippedTracking number and link
password-reset.tsxcustomer.password_reset_requestedReset button and fallback link
Customize templates by editing these files directly. They use @react-email/components for email-safe layout primitives.

​
Previewing

npm run email:dev
Opens the react-email dev server with mock data for all templates at http://localhost:3000.

​
Webhook Handler

The webhook route (src/app/api/webhooks/spree/route.ts) uses createWebhookHandler from src/lib/spree/webhooks: 
import { createWebhookHandler } from '@/lib/spree/webhooks'

export const POST = createWebhookHandler({
  secret: process.env.SPREE_WEBHOOK_SECRET!,
  handlers: {
    'order.completed': handleOrderCompleted,
    'order.canceled': handleOrderCanceled,
    'order.shipped': handleOrderShipped,
    'customer.password_reset_requested': handlePasswordReset,
  },
})
To add a new email type:
  1. Create a template in src/lib/emails/
  2. Add a handler function in src/lib/webhooks/handlers.ts
  3. Register the event in route.ts
  4. Subscribe to the event in Spree Admin → Webhooks

​
Local Development

In dev, emails are written to .next/emails/ as HTML files — no Resend key needed. Use Cloudflare Tunnel to receive webhooks locally: 
cloudflared tunnel --url http://localhost:3001
For full setup details, see Sending out Emails.

​
Building a Custom Storefront

If you prefer to build from scratch instead of forking the starter, you can use the @spree/sdk package directly in any Next.js application. The storefront’s src/lib/spree/ directory contains reusable helpers for cookie-based auth, locale resolution, middleware, and webhook verification that you can copy into your own project.