Ecommerce Starter Template

1. Overview

create-profound-next today scaffolds a generic Next.js + Profound CMS starter. This PRD proposes a second, opinionated ecommerce template that ships a complete, deployable storefront: a Stripe-backed checkout exposed as a headless UI component, plus a product catalog (categories and items) modeled as first-class components inside the Profound CMS admin panel.

The goal is to let a developer run a single command and get a working store where a non-technical merchant can create categories, add products, set prices, and publish — with payments handled by Stripe and the entire visual layer editable in the CMS.

2. Problem & Goals

Problem

Building an ecommerce site on a CMS usually means stitching together a payments provider, a product data model, a checkout UI, and a content-editing experience by hand. There is no turnkey path from "scaffold" to "merchant-editable store with real payments."

Goals

• Scaffold a production-shaped storefront in one command (npx create-profound-next --template ecommerce).
• Model the catalog (categories + items) as CMS components a merchant edits without touching code.
• Ship Stripe checkout as a headless component — logic and state provided, styling owned by the developer.
• Keep the template thin, typed, and consistent with the existing base template's conventions.

Non-Goals

• A full order-management / fulfillment dashboard (Stripe Dashboard is the source of truth for orders v1).
• Inventory reservations, multi-currency tax engines, or subscriptions (future iterations).
• Replacing Stripe Checkout — we wrap it, we don't rebuild the PCI surface.

3. Target Users

4. CMS Components (Admin Panel)

Two new CMS components are registered in the catch-all route's registry (see [...slug]/page.tsx) and exposed in the admin panel for merchant editing.

4.1 Category component

4.2 Item (product) component

5. Headless Stripe Checkout Component

Checkout ships as a headless component: it owns cart state, line-item validation, and the call to create a Stripe Checkout Session, but renders no opinionated markup. The developer supplies the UI via render props / children, so it adapts to any design.

5.1 Shape

// headless: logic + state, zero styling
const {
  items,            // cart line items
  addItem, removeItem, updateQty,
  subtotal,         // derived, display-only
  checkout,         // () => redirects to Stripe Checkout
  status,           // 'idle' | 'loading' | 'redirecting' | 'error'
  error,
} = useCart();

<Checkout>
  {({ checkout, status }) => (
    <button onClick={checkout} disabled={status === 'loading'}>
      Pay
    </button>
  )}
</Checkout>

5.2 Server flow

1. Client calls a Server Action / route handler with item ids + quantities.
2. Server resolves each id to its stripePriceId from the CMS, ignoring any client-sent price.
3. Server creates a Stripe Checkout Session and returns the redirect URL.
4. Client redirects to Stripe-hosted checkout; Stripe handles card entry (PCI scope stays with Stripe).
5. A /api/stripe/webhook handler verifies checkout.session.completed and is the trusted fulfillment signal.

6. Architecture & File Additions

Built on the existing base template (ParametricRoutePage, Refresher, createCmsProxy). New files added under src/templates/ecommerce/:

src/templates/ecommerce/
  src/
    app/
      [...slug]/page.tsx        # registry += { Category, Item }
      cart/page.tsx             # cart + headless <Checkout>
      api/stripe/
        checkout/route.ts       # create Checkout Session
        webhook/route.ts        # verify + fulfill
    components/
      Category.tsx              # CMS component
      Item.tsx                  # CMS component
      ProductGrid.tsx
    lib/
      stripe.ts                 # server Stripe client
      useCart.ts                # headless cart hook
  next.config.mjs
  _gitignore
  tsconfig.json

The CLI's generatePackageJson() adds stripe and @stripe/stripe-js alongside the existing cms-renderer dependency when the ecommerce template is selected.

7. Environment Variables

8. Requirements (MoSCoW)

9. Success Metrics

• Time-to-first-store: < 15 minutes from scaffold to a test-mode purchase completing.
• Zero-code catalog edit: a merchant creates a category + product and sees it live without a developer.
• Checkout integrity: 100% of charges derive their amount server-side from Stripe, never the client.
• Adoption: ecommerce template selected in a meaningful share of scaffolds within one quarter of launch.

10. Risks & Open Questions

11. Milestones