Next.js SaaS

Your project

Live preview — CLAUDE.md

# My SaaS

TailorMD recipe: **Next.js SaaS**

## Stack

- **Framework:** Next.js (App Router), TypeScript strict
- **Auth:** Clerk
- **Database:** Neon Postgres
- **Payments:** Stripe
- **Deploy:** Vercel
- **UI:** shadcn/ui + Tailwind CSS

## Folder map

```
app/
  (auth)/          # sign-in, sign-up
  (dashboard)/     # protected routes
  api/             # route handlers only — no business logic
components/
  ui/              # shadcn primitives
  features/        # domain components
lib/
  db/              # queries, schema
  auth/            # auth helpers
  stripe/          # billing (if applicable)
```

## Non-negotiables

- Never commit `.env` or secrets
- Validate all API inputs with Zod
- Server Components by default; `"use client"` only when needed
- No direct DB calls from Client Components
- Use Server Actions for mutations where possible
- Never expose Stripe secret keys or webhook secrets to the client

## Naming and style

- Files: `kebab-case.tsx`
- Components: `PascalCase`
- Hooks: `useCamelCase`
- DB tables: `snake_case`
- Prefer named exports for components; default export only for `page.tsx` / `layout.tsx`

## Commands

```bash
npm run dev          # local dev
npm run build        # production build
npm run lint         # eslint
npm run test         # vitest
npx drizzle-kit push # schema push (adjust for your ORM)
```

## Ship checklist

Before merging or deploying:

- [ ] Types pass (`npm run build`)
- [ ] Lint clean
- [ ] Tests pass for changed paths
- [ ] Auth flows tested (sign-in, protected route, sign-out)
- [ ] No secrets in diff
- [ ] Env vars documented in `.env.example`
- [ ] Migrations applied or schema synced

## Payments (Stripe)

- Webhook handlers must verify signatures
- Idempotent subscription updates
- Never trust client-side price IDs without server validation

## Deploy (Vercel)

- Preview deploys on every PR
- Production deploy from `main` only
- Run build locally before pushing breaking changes