better-auth Integration

Next.js 16 Breaking Changes

# Migration codemod
npx @next/codemod@latest middleware-to-proxy .

What Matters Here

• Secret must be 32+ chars – Weak secrets = broken auth
• Database schema must match your plugins – CLI generates it: npx @better-auth/cli generate
• Session cookies require headers – Server-side: auth.api.getSession({ headers: await headers() })
• Email functions are YOUR responsibility – better-auth calls them, you implement sending

Required Clarifications

Before implementing, clarify:

1. Which auth methods? (email/password, social, magic link, passkey)
2. Which database adapter? (Prisma, Drizzle, or built-in Kysely)
3. Which social providers? (Google, GitHub, Discord, etc.)
4. Need 2FA? (TOTP authenticator apps)
5. Email provider? (Resend, SendGrid, Nodemailer, etc.)

Fastest Correct Path

1. Install: npm install better-auth
2. Create lib/auth.ts (server config)
3. Create lib/auth-client.ts (client config)
4. Create app/api/auth/[...all]/route.ts
5. Run: npx @better-auth/cli generate
6. Run: npx prisma db push (or drizzle equivalent)
7. Add proxy.ts for route protection (Next.js 16)
8. Build your custom UI forms

What Can Go Wrong

How Do I Know I’m Done?

• AUTH_SECRET is 32+ chars in .env.local
• AUTH_URL matches your domain (http://localhost:3000 for dev)
• Database tables created (user, session, account, verification)
• /api/auth/session returns session data when logged in
• Protected routes redirect to login when unauthenticated
• Email verification works (if enabled)
• Social login redirects correctly (if enabled)

Must Follow

• Store ALL secrets in environment variables
• Use auth.api.getSession() server-side, NOT client methods
• Always run CLI generate after adding plugins
• Enable email verification for production
• Use HTTPS in production (required for secure cookies)
• Use proxy.ts for route protection in Next.js 16

Must Avoid

• Hardcoding secrets in source code
• Using edge runtime in proxy.ts (not supported)
• Skipping email verification in production
• Calling authClient.getSession() in server components
• Manual schema creation (use CLI instead)
• Forgetting await on headers(), params, searchParams

Reference Files

Official Documentation

Quick Start Commands

# Install
npm install better-auth

# Generate schema (after configuring auth.ts)
npx @better-auth/cli generate

# Push to database (Prisma)
npx prisma db push

# Push to database (Drizzle)
npx drizzle-kit generate && npx drizzle-kit migrate

# Migrate middleware to proxy (Next.js 16)
npx @next/codemod@latest middleware-to-proxy .