AUTH STARTER · PROJECT STRUCTURE
Project structure
A tour of the folders that matter, the files you'll edit, and the ones you can safely ignore.
We tried to keep the layout boring on purpose. If you've used Next.js App Router, nothing here will surprise you. The only opinionated bit is splitting auth config into a shared file and a server-only file — that's covered next.
Top-level
Terminal
src/
├── auth.config.ts // shared config (client + server)
├── auth.config.server.ts // server-only secrets
├── proxy.ts // Next.js 16 route protection (replaces middleware.ts)
│
├── app/
│ ├── (auth)/ // sign-in, sign-up, forgot, reset, 2fa pages
│ ├── (app)/ // dashboard (protected)
│ ├── api/auth/[...all]/ // Better Auth catch-all route
│ └── page.tsx // landing page
│
├── lib/
│ ├── env.ts // T3 Env + Zod validation
│ ├── auth.ts // Better Auth server instance
│ ├── auth-client.ts // Better Auth React client
│ ├── auth-helpers.ts // getSession / requireSession / requireGuest
│ ├── email.ts // Resend sender
│ ├── emails/ // React Email templates
│ └── types.ts // SessionUser type (extends Better Auth user)
│
├── db/
│ ├── index.ts // Drizzle client (Neon HTTP)
│ └── schema/auth.ts // user, session, account, verification, twoFactor, passkey
│
├── components/auth/ // all auth UI (sign-in, sign-up, 2fa setup, passkey, etc.)
├── hooks/use-captcha.ts // Turnstile token state
└── ...The files you'll actually touch
- src/auth.config.ts — toggle plugins, change session length, rename routes. 90% of customization happens here.
- src/db/schema/auth.ts — add your own tables and user fields.
- src/lib/email.ts + src/lib/emails/* — customize what auth emails look like.
- src/components/auth/* — restyle the sign-in card, change buttons, swap layouts.
- src/app/(app)/dashboard/page.tsx — your starting point for the logged-in app.
The files you almost never touch
- src/lib/auth.ts — Better Auth instance. Edit only when adding a brand new plugin.
- src/lib/auth-client.ts — mirrors auth.ts on the client. Same rule.
- src/proxy.ts — reads the config. You add a route prefix to authConfig, not here.
- src/app/api/auth/[...all]/route.ts — pure boilerplate. Better Auth handler. Leave it.
Why proxy.ts, not middleware.ts?
Next.js 16 renamed middleware.ts to proxy.ts and the exported function from middleware to proxy. If you're coming from Next.js 15, that's the rename — same idea, same runtime.