vibe-stack CLAUDE.md

CLAUDE.md — Vibe Stack Architecture Rules

For use with Claude Code (Anthropic's agentic CLI)

These rules prevent the most common AI hallucinations in Next.js 15 + Supabase + Stripe projects.

Project Overview

This is a Next.js 15 + Supabase + Stripe application using the App Router, TypeScript strict mode, and Tailwind CSS. All server-side auth MUST use getUser(), never getSession().

Tech Stack

• Next.js 15 (App Router only — no Pages Router)
• React 19
• TypeScript (strict mode)
• Supabase (auth, database, storage)
• Stripe (payments via Checkout Sessions)
• Tailwind CSS + shadcn/ui
• Zod (validation at every boundary)

Critical Build Commands

npm run dev          # Start dev server
npm run build        # Production build (catches type errors)
npm run lint         # ESLint
npx tsc --noEmit     # Type check without emitting

SECURITY RULES — NEVER VIOLATE

<security_critical>

1. NEVER use supabase.auth.getSession() in server-side code (Server Components, Server Actions, Route Handlers, middleware). It reads the JWT from cookies WITHOUT verifying it — a forged token passes silently. ALWAYS use supabase.auth.getUser() which makes a verification call to the Supabase auth server.

2. NEVER import from @supabase/auth-helpers-nextjs — it is DEPRECATED. Always use @supabase/ssr for both createBrowserClient (client) and createServerClient (server).

3. NEVER put auth enforcement logic in middleware.ts. Middleware runs on Edge Runtime and cannot securely verify Supabase JWTs. Middleware should ONLY call updateSession() to refresh tokens. Auth enforcement MUST happen in layouts/pages via getUser().

4. NEVER build a custom credit card form. ALWAYS redirect to Stripe Checkout. Custom forms create PCI compliance liability.

5. NEVER handle Stripe webhook events without calling stripe.webhooks.constructEvent() first to verify the stripe-signature header. Without this, anyone can POST fake events to your webhook endpoint.

6. NEVER upload files directly from client code using the Supabase anon key — it allows writing to any storage path. ALWAYS generate signed upload URLs server-side, scoped to user.id.