patterns-and-errors

Next.js E-commerce Patterns and Errors

Inline cart/Stripe/checkout snippets, error summary, failure modes, and rationalizations. Deeper patterns in sibling references.

Shopping Cart Implementation

See [shopping-cart-patterns.md](shopping-cart-patterns.md) for complete implementation.

**Server Component (cart display)**:

// app/cart/page.tsx
import { getCart } from '@/lib/cart'

export default async function CartPage() {
  const cart = await getCart() // Server-side cart fetch
  return <CartDisplay items={cart.items} />
}

**Client Component (cart updates)**:

// components/AddToCartButton.tsx
'use client'
import { addToCart } from '@/actions/cart'

export function AddToCartButton({ productId }: { productId: string }) {
  return (
    <button onClick={() => addToCart(productId)}>
      Add to Cart
    </button>
  )
}

**Server Action (cart mutation)**:

// actions/cart.ts
'use server'
export async function addToCart(productId: string) {
  const cart = await getCart()
  await db.cartItem.create({
    data: { cartId: cart.id, productId, quantity: 1 }
  })
  revalidatePath('/cart')
}

Stripe Integration

See [stripe-integration.md](stripe-integration.md) for complete implementation.

**Payment Intent Creation**:

// app/api/checkout/route.ts
import Stripe from 'stripe'
const stripe = new Stripe(process.env.STRIPE_SECRET_KEY!)

export async function POST(req: Request) {
  const { amount } = await req.json()

  const paymentIntent = await stripe.paymentIntents.create({
    amount: amount * 100, // Convert to cents
    currency: 'usd',
    metadata: { orderId: '...' }
  })

  return Response.json({ clientSecret: paymentIntent.client_secret })
}

**Webhook Handler**:

// app/api/webhooks/stripe/route.ts
import { headers } from 'next/headers'

export async function POST(req: Request) {
  const body = await req.text()
  const signature = headers().get('stripe-signature')!

  const event = stripe.webhooks.constructEvent(
    body,
    signature,
    process.env.STRIPE_WEBHOOK_SECRET!
  )

  if (event.type === 'payment_intent.succeeded') {
    const paymentIntent = event.data.object
    await fulfillOrder(paymentIntent.metadata.orderId)
  }

  return Response.json({ received: true })
}

Error Handling

See [error-catalog.md](error-catalog.md) for full catalog.

| Error | Cause | Fix | |-------|-------|-----| | Webhook signature verification failed | Secret mismatch or invalid sig | Verify STRIPE_WEBHOOK_SECRET, use raw body (not parsed JSON) | | Inventory oversold | No stock validation before order | Prisma transaction: check stock and decrement atomically | | Payment Intent already succeeded | Duplicate webhook events | Implement idempotency with order status checks |

Preferred Patterns

See [preferred-patterns.md](preferred-patterns.md) for full catalog.

| Signal | Risk | Fix | |--------|------|-----| | Saving card numbers in DB | PCI violation | Use Stripe tokens exclusively | | Computing total in React component | Client can manipulate prices | Calculate prices server-side | | Creating orders without checking stock | Overselling | Validate stock in transaction before order creation |

Anti-Rationalization

See [shared-patterns/anti-rationalization-core.md](../../../skills/shared-patterns/anti-rationalization-core.md) for universal patterns.

| Rationalization | Why Wrong | Required Action | |----------------|-----------|-----------------| | "Stripe test mode is enough for production" | Test keys won't process real payments | Use production keys for live site | | "Client-side validation prevents invalid prices" | Client can be manipulated | Validate prices server-side | | "Checking stock once is sufficient" | Race conditions cause overselling | Atomic transaction for check+decrement | | "Webhook might fire twice, that's rare" | Webhooks DO fire multiple times | Implement idempotency checks | | "localhost webhook testing isn't needed" | Production issues are expensive | Use Stripe CLI for local testing |

Blocker Criteria

Resolve routine issues from repository evidence and existing authorization. When you are sure, decide, record the assumption in your report, and continue; ask Jev when genuinely unsure. Ask only when these situations leave a material decision uncovered:

| Situation | Ask This | |-----------|----------| | Multiple payment providers requested | "Use Stripe, PayPal, or both?" | | Complex tax requirements | "Manual tax calculation or integrate TaxJar/Avalara?" | | Multi-currency needed | "Which currencies? Fixed rates or dynamic conversion?" | | Subscription vs one-time unclear | "One-time purchases, subscriptions, or both?" |