// lib/commerce/types.ts
export interface CommerceProduct {
  id: string;
  handle: string;
  title: string;
  price: { amount: number; currency: string };
  images: Array<{ url: string; alt: string }>;
  variants: Array<{ id: string; sku: string; available: boolean }>;
}

export interface CartLineItem {
  variantId: string;
  quantity: number;
}

// app/products/[handle]/page.tsx
import { notFound } from 'next/navigation';
import { CommerceProduct } from '@/lib/commerce/types';

async function fetchProduct(handle: string): Promise<CommerceProduct | null> {
  const response = await fetch(
    `${process.env.COMMERCE_API_URL}/products/${handle}`,
    { next: { revalidate: 3600, tags: ['product-catalog'] } }
  );
  
  if (!response.ok) return null;
  return response.json();
}

export default async function ProductDetailPage({ params }: { params: { handle: string } }) {
  const product = await fetchProduct(params.handle);
  
  if (!product) notFound();

  return (
    <article className="grid grid-cols-1 md:grid-cols-2 gap-8 p-6">
      <div className="space-y-4">
        <h1 className="text-3xl font-bold">{product.title}</h1>
        <p className="text-xl">${product.price.amount} {product.price.currency}</p>
      </div>
      <div className="space-y-4">
        {product.images.map((img, idx) => (
          <img key={idx} src={img.url} alt={img.alt} className="rounded-lg w-full" />
        ))}
      </div>
    </article>
  );
}

// lib/commerce/cart-context.tsx
'use client';

import { createContext, useContext, useOptimistic, useTransition } from 'react';
import { CartLineItem } from './types';

interface CartState {
  items: CartLineItem[];
  addItem: (item: CartLineItem) => void;
  removeItem: (variantId: string) => void;
}

const CartContext = createContext<CartState | null>(null);

export function CartProvider({ children }: { children: React.ReactNode }) {
  const [items, setItems] 

= useOptimistic<CartLineItem[]>([]); const [isPending, startTransition] = useTransition();

const addItem = (newItem: CartLineItem) => { startTransition(async () => { setItems(prev => { const existing = prev.find(i => i.variantId === newItem.variantId); if (existing) { return prev.map(i => i.variantId === newItem.variantId ? { ...i, quantity: i.quantity + newItem.quantity } : i ); } return [...prev, newItem]; });

  await fetch('/api/cart/sync', {
    method: 'POST',
    body: JSON.stringify({ action: 'add', item: newItem })
  });
});

};

const removeItem = (variantId: string) => { startTransition(() => { setItems(prev => prev.filter(i => i.variantId !== variantId)); }); };

return ( <CartContext.Provider value={{ items, addItem, removeItem }}> {children} </CartContext.Provider> ); }

export const useCart = () => { const ctx = useContext(CartContext); if (!ctx) throw new Error('useCart must be used within CartProvider'); return ctx; };

### Step 4: Secure Payment Intent Creation
Never process payments on the client. Create a dedicated API route that validates cart contents, calculates taxes/shipping server-side, and generates a payment intent. This keeps sensitive gateway keys and business logic isolated from the browser.

```typescript
// app/api/checkout/route.ts
import { NextRequest, NextResponse } from 'next/server';
import Stripe from 'stripe';

const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!);

export async function POST(req: NextRequest) {
  try {
    const { items, currency } = await req.json();
    
    const lineItems = items.map((item: any) => ({
      price_data: {
        currency,
        product_data: { name: item.name },
        unit_amount: Math.round(item.price * 100),
      },
      quantity: item.quantity,
    }));

    const session = await stripe.checkout.sessions.create({
      mode: 'payment',
      line_items: lineItems,
      success_url: `${process.env.NEXT_PUBLIC_BASE_URL}/checkout/success`,
      cancel_url: `${process.env.NEXT_PUBLIC_BASE_URL}/checkout/cancel`,
      metadata: { cart_id: crypto.randomUUID() },
    });

    return NextResponse.json({ url: session.url });
  } catch (error) {
    return NextResponse.json({ error: 'Checkout initialization failed' }, { status: 500 });
  }
}

Architecture Decisions & Rationale

• Server Components for Catalog: Product pages are read-heavy and SEO-critical. Rendering them on the server eliminates hydration mismatches and guarantees crawlers receive complete markup.
• Optimistic Cart Updates: Commerce UX demands instant feedback. useOptimistic provides immediate UI state changes while background sync maintains data integrity without blocking interactions.
• Isolated Payment Route: PCI compliance scope shrinks dramatically when payment details never touch the client. The API route acts as a trusted intermediary, handling tax calculation, inventory reservation, and gateway communication.
• Cache Tags over Fixed TTL: Commerce data changes unpredictably. Using tags: ['product-catalog'] allows programmatic revalidation via webhook triggers rather than relying on stale time-based expiration.

Pitfall Guide

1. Treating the Frontend as the Source of Truth for Pricing

Explanation: Developers often fetch product prices once and cache them aggressively. Commerce pricing changes due to promotions, currency fluctuations, or inventory adjustments. Serving stale prices causes checkout failures and customer disputes. Fix: Always validate pricing server-side during checkout intent creation. Use short TTLs for price data and implement webhook-driven cache invalidation when the backend reports price updates.

2. Ignoring PCI-DSS Scope in Custom Checkouts

Explanation: Building a custom checkout form that collects raw card numbers expands PCI compliance requirements from SAQ-A to SAQ-D, triggering annual audits, network segmentation, and heavy documentation. Fix: Use hosted payment fields or redirect-based checkout sessions (Stripe Checkout, Shopify Payments redirect). Never render raw card inputs in your DOM. Keep your application scope limited to SAQ-A.

3. Over-Fetching Commerce APIs on Every Route Change

Explanation: Next.js re-renders server components on navigation. If every product page fetches the full catalog or variant matrix, API rate limits trigger and latency compounds. Fix: Implement response caching with fetch options, use GraphQL fragments to request only needed fields, and leverage edge runtime for geographic proximity to commerce APIs.

4. Neglecting Edge Caching for Product Catalogs

Explanation: Product pages are static between updates but dynamic in nature. Relying solely on origin fetches increases Time to First Byte (TTFB) and hurts Core Web Vitals. Fix: Deploy ISR (Incremental Static Regeneration) with webhook-triggered revalidation. Configure CDN headers to cache catalog responses at the edge, invalidating only when inventory or pricing changes.

5. Underestimating State Hydration Costs

Explanation: Shipping large cart contexts or product configurators to the client increases JavaScript bundle size and delays interactive readiness. Hydration mismatches between server and client state cause layout shifts. Fix: Serialize only essential cart data for the client. Use progressive enhancement: render the product shell statically, then hydrate interactive elements (quantity selectors, variant pickers) only when needed.

6. Hardcoding Currency and Region Logic

Explanation: Assuming a single currency or tax jurisdiction breaks international scaling. Exchange rates fluctuate, and tax rules vary by shipping destination. Fix: Externalize currency conversion to a dedicated service. Calculate taxes server-side using a compliance API (Avalara, TaxJar) based on the shipping address, not the customer's IP.

7. Skipping Idempotency in Payment Webhooks

Explanation: Payment gateways retry webhook deliveries. Without idempotency keys, duplicate events create double charges, duplicate order records, and inventory desynchronization. Fix: Store processed webhook event IDs in your database. Before processing any payment event, check if the ID exists. Return 200 OK immediately for duplicates to acknowledge receipt without reprocessing.

Production Bundle

Action Checklist

• Audit current monthly revenue and technical team capacity before selecting architecture
• Map API contracts for products, cart, and checkout before writing UI components
• Implement server-side price validation during payment intent creation
• Configure cache tags and webhook-driven revalidation for catalog data
• Isolate payment processing to a dedicated API route to maintain SAQ-A compliance
• Add idempotency checks to all payment and inventory webhooks
• Set up synthetic monitoring for checkout flow latency and error rates
• Document migration path for product data if switching platforms later

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
MVP / Product Validation	Hosted SaaS Platform	Days to launch, zero infrastructure management, app ecosystem covers early needs	Low upfront, predictable monthly OPEX
Scaling Brand ($50k–$200k/mo)	Headless Hybrid	Retains backend operations while unlocking frontend performance and SEO control	Moderate upfront dev cost, platform fees continue
High-Volume / Custom Logic ($500k+/yr)	Custom React Frontend	Eliminates platform margins, enables complex B2B pricing, full conversion optimization	High upfront, lower long-term OPEX, higher engineering overhead
Content-Heavy Commerce	Custom React Frontend	Unified codebase for editorial and product pages, shared routing, consistent design system	Moderate dev cost, eliminates CMS + commerce platform duplication

Configuration Template

# .env.local
NEXT_PUBLIC_BASE_URL=https://yourstore.com
COMMERCE_API_URL=https://api.yourbackend.com/v1
STRIPE_SECRET_KEY=sk_live_...
STRIPE_WEBHOOK_SECRET=whsec_...
NEXT_REVALIDATE_SECRET=your-revalidation-token

# next.config.mjs
/** @type {import('next').NextConfig} */
const nextConfig = {
  images: {
    domains: ['cdn.yourbackend.com', 'images.unsplash.com'],
    formats: ['image/avif', 'image/webp'],
  },
  experimental: {
    optimizePackageImports: ['@commerce/ui', '@commerce/utils'],
  },
  async rewrites() {
    return [
      { source: '/api/:path*', destination: '/api/:path*' },
    ];
  },
};

export default nextConfig;

Quick Start Guide

1. Initialize the project: Run npx create-next-app@latest commerce-store --typescript --tailwind --app. Select the App Router and enable TypeScript.
2. Configure environment variables: Copy the .env.local template. Add your commerce backend URL and Stripe keys. Never commit secrets to version control.
3. Create the data layer: Set up lib/commerce/types.ts and lib/commerce/client.ts to handle authenticated API requests with retry logic and timeout handling.
4. Build the product shell: Implement a Server Component for /products/[handle] that fetches data with cache tags. Add a client component for variant selection and cart actions.
5. Deploy and validate: Push to Vercel or your preferred edge host. Run Lighthouse audits on product and checkout pages. Verify webhook endpoints respond with 200 and handle idempotency correctly.