Prisma + Better Auth + Next.js Setup Guide
Source: prisma.io/docs/guides/authentication/better-auth/nextjs
Prerequisites
- Node.js 20+, Next.js App Router + TypeScript
- PostgreSQL (Neon, Supabase, local) — for MySQL/SQLite swap the adapter
Steps Overview — Core (Basic Setup)
| Step | Folder | Files | What |
|---|---|---|---|
| 1 | 1-setup-project/ | create-nextjs-app | Create Next.js project |
| 2.1 | 2-setup-prisma/ | install-dependencies | Install Prisma + pg |
| 2.2 | configure-prisma | prisma.config.ts | |
| 2.3 | generate-client | Generate typed client | |
| 2.4 | global-client | Singleton src/lib/db/index.ts | |
| 3.1 | 3-setup-better-auth/ | install-configure | Install + src/lib/auth.ts |
| 3.2 | add-auth-models | User, Session, Account (with @@map) | |
| 3.3 | migrate-database | Run migration | |
| 4.1 | 4-api-routes/ | setup-routes | Catch-all + auth client |
| 5.1 | 5-pages/ | sign-up | Sign up form |
| 5.2 | sign-in | Sign in form | |
| 5.3 | dashboard | Protected dashboard | |
| 5.4 | home | Landing page | |
| 6 | 6-test/ | test-app | Test + troubleshoot |
Steps Overview — Advanced (Production-Grade)
| Step | Folder | Files | What |
|---|---|---|---|
| 2.5 | 2-setup-prisma/ | neon-adapter | Neon serverless adapter + dual URLs |
| 2.6 | slow-query-logging | Structured slow query detection | |
| 3.4 | 3-setup-better-auth/ | oauth-providers | Google + GitHub OAuth |
| 3.5 | two-factor | TOTP 2FA plugin | |
| 3.6 | email-verification | Resend + React Email templates | |
| 3.7 | session-config | Session, cookies, trustedOrigins | |
| 4.2 | 4-api-routes/ | rate-limiting | Upstash Redis + account lockout |
| 4.3 | audit-logging | Structured auth event logging |
Key Files
| File | Purpose |
|---|---|
prisma.config.ts | Datasource URL (Prisma 7: DIRECT_URL fallback) |
src/lib/db/index.ts | Global Prisma + Neon adapter + slow query logging |
src/lib/auth.ts | Better Auth config (email, OAuth, 2FA, hooks) |
src/lib/auth-client.ts | React client (signIn, signUp, signOut, useSession, twoFactor) |
src/lib/rate-limit.ts | Upstash Redis rate limiter + in-memory fallback |
src/lib/auth/audit-log.ts | Structured auth event logger |
src/lib/email/resend.ts | Resend email sender + fire-and-forget variant |
src/app/api/auth/[...all]/route.ts | Auth API + rate limit + account lockout |
Quick Commands
# Core
npm install prisma tsx --save-dev
npm install @prisma/client @prisma/adapter-neon better-auth
npx @better-auth/cli@latest secret
npx @better-auth/cli generate
npx prisma migrate dev --name add-auth-models
# Advanced
npm install @upstash/ratelimit @upstash/redis resend react-emailKey Patterns
- Prisma 7:
prisma.config.tsfor datasource, NOTschema.prisma - @@map: All models use
@@map("lowercase")— required by Better Auth - Neon dual URLs:
DATABASE_URL(pooled) for queries,DIRECT_URLfor migrations - trustedOrigins: Required if port!= 3000 or in production
- Rate limiting: Upstash Redis (prod) / in-memory (dev), 4 presets
- Account lockout: 10 failures in 15 min → 30 min lockout
- IP extraction: Last
X-Forwarded-ForIP (proxy-set, not spoofable) - OAuth: Conditional enable via
Boolean(ID && SECRET) - Email verification: Auto-enable via
Boolean(process.env.RESEND_API_KEY) - Audit log: JSON in prod, readable in dev, no PII
Scaffold Script
python .claude/skills/prisma-better-auth-nextjs/scripts/scaffold.py [target-dir]