clownnvd/prisma-better-auth-nextjs

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-email

Key Patterns

• Prisma 7: prisma.config.ts for datasource, NOT schema.prisma
• @@map: All models use @@map("lowercase") — required by Better Auth
• Neon dual URLs: DATABASE_URL (pooled) for queries, DIRECT_URL for 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-For IP (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]