Better Auth

Better Auth — cross-stack authentication for TypeScript

Better Auth is a framework-agnostic auth library: one betterAuth() server instance owns the logic, a tiny per-framework adapter mounts it as HTTP routes, and a typed client SDK talks to those routes. The same core works in Next.js, SvelteKit, Nuxt, Solid, Remix, Astro, TanStack Start, Express, Hono, Elysia, Fastify, or raw Node — only the mount and the client import change.

This skill keeps the cross-cutting rules here and pushes the per-framework, per-adapter, and per-plugin detail into references/. Read the relevant reference before writing integration code — the import paths and method names are load-bearing and easy to get subtly wrong.

The mental model (4 moving parts)

.env  →  auth.ts (server instance)  →  mount handler (/api/auth/*)  →  auth-client.ts (client SDK)
secret      betterAuth({db, ...})        toNextJsHandler / auth.handler     createAuthClient({...})

1. Server instance (auth.ts/lib/auth.ts): betterAuth({ database, emailAndPassword, socialProviders, plugins }). One file, the source of truth.
2. Database: an adapter (Drizzle/Prisma/Mongo) or a raw driver (built-in Kysely). Then generate the schema and migrate.
3. Mount: expose auth.handler at the catch-all route /api/auth/* using your framework's adapter.
4. Client: createAuthClient from the subpath for your front-end framework; call signIn/signUp/useSession.

Facts that prevent broken work

Read this first — each row is a real failure integrators hit.

Preflight

Confirm the environment + detect the right handler/adapter BEFORE writing code, so the first failure points at config, not a bug:

bash scripts/better-auth-preflight.sh                 # node, secret, env + framework/ORM detection
bash scripts/better-auth-preflight.sh --gen-secret    # also print a fresh BETTER_AUTH_SECRET
bash scripts/better-auth-preflight.sh --dir ./apps/web # check a sub-package in a monorepo

It reads the nearest package.json and tells you the exact handler import and database adapter for the stack it finds.

Build it in one command (scaffold)

The fastest path to a working setup is to generate it, then customize. The scaffolder emits a complete, runnable starter (server instance + mounted route + client + schema + .env.example) wired for your framework and database:

node scripts/scaffold-better-auth.mjs --out ./my-auth --framework next --db drizzle-pg
node scripts/scaffold-better-auth.mjs --framework express --db sqlite --plugins admin,organization
node scripts/scaffold-better-auth.mjs --help     # all flags; --dry-run previews

Then: cd my-auth && npm install, fill .env, run the CLI generate + migrate shown in the emitted README, and npm run dev. The output is a correct skeleton, not a black box — refine it with the references below.

Canonical quick start (Next.js App Router + Drizzle/Postgres)

The most common stack, end to end. Swap the two starred lines per the references for any other framework/database.

// lib/auth.ts — the server instance (source of truth)
import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";   // ★ database
import { nextCookies } from "better-auth/next-js";
import { db } from "@/db";

export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "pg" }),              // ★ provider: pg|mysql|sqlite
  emailAndPassword: { enabled: true },
  plugins: [nextCookies()],   // MUST stay LAST so server actions can set cookies
});

// app/api/auth/[...all]/route.ts — mount the catch-all handler
import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { POST, GET } = toNextJsHandler(auth);

// lib/auth-client.ts — the typed client
import { createAuthClient } from "better-auth/react";            // ★ framework subpath
export const authClient = createAuthClient();                   // same origin → no baseURL needed

# create the tables: generate the Drizzle schema, then migrate with drizzle-kit
npx @better-auth/cli@latest generate     # writes auth-schema.ts
npx drizzle-kit generate && npx drizzle-kit migrate

// use it (React) — { data, error } everywhere; useSession is reactive
const { data: session, isPending } = authClient.useSession();
await authClient.signUp.email({ email, password, name });
await authClient.signIn.email({ email, password, callbackURL: "/dashboard" });
await authClient.signOut();

// protect a server route / page — the AUTHORITATIVE check
import { auth } from "@/lib/auth";
import { headers } from "next/headers";
const session = await auth.api.getSession({ headers: await headers() });
if (!session) redirect("/sign-in");   // session = { user, session }

Choose your pieces (then read the reference)

Framework — exact mount + route path + client + session read + route protection live in references/frameworks.md:

Database — adapters, schema, generate/migrate, custom table names, numeric IDs in references/database-adapters.md:

Client — createAuthClient subpath + how useSession differs per framework, error handling, custom-field typing in references/client.md.

Plugins — the full catalog (2FA, magic link, email OTP, passkey, username, anonymous, phone, organization, admin, apiKey, jwt, bearer, multiSession, oneTap, captcha, haveIBeenPwned, oidcProvider, sso…) with exact imports, methods, and which add schema in references/plugins.md.

Where to go next

Scripts

Common mistakes

Resources

• Docs: https://better-auth.com/docs · LLM index: https://better-auth.com/llms.txt
• Options reference: https://better-auth.com/docs/reference/options
• CLI: https://better-auth.com/docs/concepts/cli · Plugins: https://better-auth.com/docs/plugins
• GitHub: https://github.com/better-auth/better-auth