notque/vexjoy-agent / skills/frontend/frontend
frontend
UnverifiedFrontend: UI design, distinctive visual styles, HTML artifacts, Three.js 3D, TypeScript/React/Next.js apps, e-commerce, portfolios, React Native, web performance.
references/nextjs-ecommerce/patterns-and-errors.md
View on GitHub# 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)**:
```typescript
// 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)**:
```typescript
// 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)**:
```typescript
// 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**:
```typescript
// 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**:
```typescript
// 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](../../../../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?" |
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation). | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK). | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |