How daveyplate/better-auth-nextjs-starter works
Main components
a. Frontend (Next.js App Router)
b. Backend API (Next.js serverless functions under app/api)
c. Authentication service (Better Auth)
d. Database layer (PostgreSQL via Drizzle ORM)
e. Client-side state & data fetching (TanStack Query)
f. UI Library & Styles (shadcn/ui, TailwindCSS)
g. External services & tooling (Better-Auth CLI, migrations, Vercel)
Relationships and data flows
• User’s browser loads React pages from the Next.js frontend.
• On page load or user actions, the frontend calls internal API routes (app/api/auth/[...all]/route.ts).
• API routes use lib/auth and lib/auth-client to communicate with Better Auth (via REST or SDK) for sign-in, token validation, and session management.
• Authenticated API handlers then use Drizzle ORM (database/db.ts + schema.ts) to read/write user data in PostgreSQL.
• Client code uses TanStack Query hooks (hooks/auth-hooks.ts) to fetch and cache server data.
• UI components (components/ui/* and components/*) render based on data and auth state.
• Middleware.ts enforces route protection & redirects on the server.
Architectural patterns and design principles
• Next.js App Router – server/client boundary, automatic code splitting, server-side rendering (SSR) or static generation (SSG).
• MVC-style separation: API routes (Controller), Drizzle ORM + database (Model), React pages + components (View).
• Single codebase monorepo orchestrated by Turborepo (turbo.json).
• Environment-driven configuration (.env, drizzle.config.ts, next.config.ts).
• Hooks and provider pattern for cross-cutting concerns (auth state, themes).
Key technologies and their roles
• Next.js: Routing, SSR/SSG, API routes
• Better Auth & Better-Auth UI: Authentication backend & prebuilt React UI
• Drizzle ORM + drizzle-kit: Schema generation, migrations, type-safe DB access
• PostgreSQL: Relational data store
• TanStack Query: Client-side data fetching & caching
• shadcn/ui + TailwindCSS: Component library + styling
• Biome: Linting/formatting
• Turborepo: Build & workspace management
Detail level
• Every major folder/group (app, components, lib, database, hooks).
• Middleware or provider that impacts global behavior (e.g., auth redirects).