better-auth

Files (14)

• SKILL.md
• evals.json · evals/
• trigger_queries.json · evals/
• client.md · references/
• core-server-config.md · references/
• database-adapters.md · references/
• frameworks.md · references/
• organization-admin-rbac.md · references/
• plugins.md · references/
• security-and-production.md · references/
• social-oauth.md · references/
• better-auth-doctor.mjs · scripts/
• better-auth-preflight.sh · scripts/
• scaffold-better-auth.mjs · scripts/

SKILL.md (first lines)

# 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.

| Fact | Consequence |
|---|---|
| **`BETTER_AUTH_SECRET` is mandatory in prod** | Boot throws without it. Generate `openssl rand -base64 32`. Also set `BETTER_AUTH_URL` (baseURL) or cookies/redirects break in prod. |
| **The route MUST be a catch-all at `/api/auth/*`** | A single non-catch-all route (e.g. `/api/auth/route.ts`) silently 404s sub-paths like `/api/auth/sign-in/email`. Use `[...all]`, `*`, `$`, or `*splat` per framework. |
| **Express: mount the handler BEFORE `express.json()`** | `toNodeHandler(auth)` must run before any body parser, or the client API hangs on "pending". Scope `express.json()` to non-auth routes. (Express v5 wildcard is `/api/auth/*splat`.) |
| **Next.js server actions need `nextCookies()` as the LAST plugin** | Without it, cookies set inside server actions (e.g. server-side `signInEmail`) never reach the browser → "logged out right after sign-up". |
| **`generate` ≠ `migrate`** | `npx @better-auth/cli@latest generate` writes the schema for your ORM; only the **built-in Kysely** adapter can `migrate` directly. Drizzle/Prisma must run **their own** migrate after generate. |
| **Re-run `generate` after adding a schema plugin** | twoFactor, username, admin, organization, passkey, jwt, apiKey… add tables/columns. Forgetting to regenerate = "column/table does not exist" at runtime — the #1 plugin error. |
| **Server `auth.api.*` calls REQUIRE `headers`** | `auth.api.getSession({ headers })` — pass the request headers (Node: `fromNodeHeaders(req.headers)`). No headers = always null session. |
| **Client `baseURL` must match the server origin + `basePath`** | If the client is on a different origin, set `createAuthClient({ baseURL })` and add that origin to server `trustedOrigins`, or every call fails CORS/CSRF. |
| **Server plugin + client plugin come in pairs** | A server plugin from `better-auth/plugins` needs its client twin from `better-auth/client/plugins` (e.g. `organization()` ↔ `organizationClient()`), or the client methods/types won't exist. |
| **`passkey` (v1.4+), `sso` & `apiKey` (v1.5+) ship as scoped packages** | Import from `@better-auth/passkey`, `@better-auth/sso`, `@better-auth/api-key` (client: `.../client`). Before those versions they lived in `better-auth/plugins`. Check the installed version. |
| **Middleware cookie checks are optimistic, not authoritative** | `getSessionCookie()` only checks a cookie exists — never trust it for real authz. Do the real check with `auth.api.getSession()` in the page/route/loader. |
| **Cross-subdomain cookies need explicit config** | app.x.com ↔ api.x.com: set `advanced.crossSubDomainCookies` + `defaultCookieAttributes { sameSite:'none', secure:true, partitioned:true }`. "Works locally, breaks in prod" is almost always this. |

## Preflight

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

```bash
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:

```bash
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.

```ts
// 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
});
```

```ts
// 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);
```

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

```bash
# 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
```

```tsx
// 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();
```

From kryptobaseddev/awesome-skills, MIT.

More from kryptobaseddev/awesome-skills