Recommended default: Supabase PostgreSQL for the database host, with Better Auth inside the app for authentication and sessions. This is the fastest, most supported path.
Recommended path: run pnpm bootstrap first. The setup wizard writes .env.local, generates BETTER_AUTH_SECRET, runs pnpm db:migrate, and can also walk you through Google OAuth and email-provider config. The tabs below are the manual equivalent.
The Mental Model
Here’s how the pieces fit together:
- PostgreSQL + Drizzle = your data layer (schema, migrations, queries)
- Better Auth = your auth layer (sessions, sign-in, OAuth, magic links)
- Supabase = the recommended managed Postgres host
Better Auth runs inside your app. Supabase just hosts the database. You’re not locked into Supabase — any PostgreSQL provider that supports pgcrypto and pgvector will work.
Quick Setup
Email/Password Only
With Google OAuth
The fastest path. No OAuth, no magic links — just email and password.Set your env vars
Add these to your .env.local:NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-secret-here
DATABASE_URL=postgresql://...
If you copy the connection string from Supabase, replace the literal [YOUR-PASSWORD] placeholder with your real database password before pasting.
Email/password plus Google sign-in. A bit more setup, but a much better user experience.Set your core env vars
NEXT_PUBLIC_APP_URL=http://localhost:3000
BETTER_AUTH_SECRET=your-secret-here
DATABASE_URL=postgresql://...
Set up Google OAuth
In Google Cloud Console, add these callback URLs:
http://localhost:3000/api/auth/callback/googlehttps://yourdomain.com/api/auth/callback/google
Then add your Google credentials to .env.local:GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true
Set NEXT_PUBLIC_GOOGLE_AUTH_ENABLED=true so the Google button shows up in the UI. The backend only enables Google when GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET are also set.
Optional: Enable magic links and password reset
If you want these flows, you’ll need an email provider on both the client and server side:NEXT_PUBLIC_EMAIL_PROVIDER=resend
EMAIL_PROVIDER=resend
AUTH_EMAIL_FROM="AnotherWrapper <[email protected]>"
RESEND_API_KEY=...
resend is just the shortest example. loops and brevo are also supported.
What Better Auth Handles
- Sign-in and session cookies
- Email/password accounts
- Google OAuth
- Magic link and forgot password
- Profile bootstrap via database hooks
Email/password works without an email provider. Magic link and forgot password need a real email provider plus auth-email config once you enable those flows.
What Drizzle Handles
- Schema definition in
lib/db/schema/*
- SQL migration history in
drizzle/*
- App-side database access in
lib/db/*
When you change lib/db/schema/*, generate a new SQL migration with pnpm db:generate.
The RAG/document search features depend on the pgvector extension. The repo enables it in drizzle/0000_better_auth_baseline.sql, so your database host must support CREATE EXTENSION vector.
Can You Use Another PostgreSQL Provider?
Yes. The main requirements are:
pgcrypto supportpgvector support- Standard Drizzle/Postgres features used by the schema
Supabase is the recommended default because it gives you managed PostgreSQL plus pgvector out of the box.
Auth Helpers in the Repo
The main server-side auth helpers live in lib/auth/server.ts. Here’s the pattern:
| Helper | Use When |
|---|
getAuthContext() | Auth is optional |
requireUser() | Server pages and layouts |
requireApiUser() | API routes |
signOutCurrentSession() | Logout flows |
Verify It Works
Your auth and database setup is correct if you can:
- Sign in on
/auth
- Reach
/
- See a profile row created for your user
- Use at least one authenticated app flow
