/better-auth

name: better-auth
description: Skill for integrating Better Auth - comprehensive TypeScript authentication framework for Cloudflare D1, Next.js, Nuxt, and 15+ frameworks. Use when adding auth, encountering D1 adapter errors, or implementing OAuth/2FA/RBAC features.
license: MIT
metadata:
  keywords: "better-auth, authentication, cloudflare d1 auth, drizzle orm auth, kysely auth, self-hosted auth, typescript auth, clerk alternative, auth.js alternative, social login, oauth providers, session management, jwt tokens, 2fa, two-factor, passkeys, webauthn, multi-tenant auth, organizations, teams, rbac, role-based access, google auth, github auth, microsoft auth, apple auth, magic links, email password, better-auth setup, drizzle d1, kysely d1, session serialization error, cors auth, d1 adapter, nextjs auth, nuxt auth, remix auth, sveltekit auth, expo auth, react native auth, postgresql auth, mongodb auth, mysql auth, stripe auth, api keys, sso, saml, scim, admin dashboard, background tasks, oauth 2.1, cli, electron, i18n, instrumentation, otel, opentelemetry, test-utils, dynamic-base-url, secret-rotation, oauth-provider, mcp, passkey pre-auth, d1 native"
  version: "3.1.0"
  package_version: "1.6.0"
  last_verified: "2026-04-08"
  errors_prevented: 20
  templates_included: 4
  references_included: 32

better-auth

**Status**: Production Ready **Last Updated**: 2026-04-08 **Package**: `better-auth@1.6.0` (ESM-only) **Dependencies**: Drizzle ORM or Kysely (required for D1 complex use cases; D1 native support available in v1.5+)

---

Quick Start (5 Minutes)

Installation

**Option 1: Drizzle ORM (Recommended)**

bun add better-auth drizzle-orm drizzle-kit

**Option 2: Kysely**

bun add better-auth kysely @noxharmonium/kysely-d1

⚠️ v1.4.0+ Requirements

better-auth v1.4.0+ is **ESM-only**. Ensure:

**package.json**:

{
  "type": "module"
}

**Upgrading from v1.3.x?** Load `references/migration-guide-1.4.0.md` **Upgrading from v1.4.x?** Load `references/migration-guide-1.5.0.md`

⚠️ CRITICAL: D1 Adapter Requirements

**v1.5.0+**: D1 is now natively supported. Pass your D1 binding directly:

// ✅ SIMPLEST - D1 native (v1.5.0+)
import { betterAuth } from "better-auth";

const auth = betterAuth({
    database: env.DB, // D1 binding, auto-detected
});

For complex schemas, use Drizzle ORM:

// ✅ RECOMMENDED for complex schemas - Drizzle
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";

const auth = betterAuth({
    database: drizzleAdapter(drizzle(env.DB, { schema }), { provider: "sqlite" }),
});

// ❌ WRONG - This doesn't exist
import { d1Adapter } from 'better-auth/adapters/d1'

Minimal Setup (Cloudflare Workers + Drizzle)

**1. Create D1 Database:**

wrangler d1 create my-app-db

**2. Define Schema** (`src/db/schema.ts`):

import { integer, sqliteTable, text } from "drizzle-orm/sqlite-core";

export const user = sqliteTable("user", {
  id: text().primaryKey(),
  name: text().notNull(),
  email: text().notNull().unique(),
  emailVerified: integer({ mode: "boolean" }).notNull().default(false),
  image: text(),
});

export const session = sqliteTable("session", {
  id: text().primaryKey(),
  userId: text().notNull().references(() => user.id, { onDelete: "cascade" }),
  token: text().notNull(),
  expiresAt: integer({ mode: "timestamp" }).notNull(),
});

// See references/database-schema.ts for complete schema

**3. Initialize Auth** (`src/auth.ts`):

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { drizzle } from "drizzle-orm/d1";
import * as schema from "./db/schema";

export function createAuth(env: { DB: D1Database; BETTER_AUTH_SECRET: string }) {
  const db = drizzle(env.DB, { schema });

  return betterAuth({
    baseURL: env.BETTER_AUTH_URL,
    secret: env.BETTER_AUTH_SECRET,
    database: drizzleAdapter(db, { provider: "sqlite" }),
    emailAndPassword: { enabled: true },
  });
}

**4. Create Worker** (`src/index.ts`):

import { Hono } from "hono";
import { createAuth } from "./auth";

const app = new Hono<{ Bindings: Env }>();

app.all("/api/auth/*", async (c) => {
  const auth = createAuth(c.env);
  return auth.handler(c.req.raw);
});

export default app;

**5. Deploy:**

bunx drizzle-kit generate
wrangler d1 migrations apply my-app-db --remote
wrangler deploy

---

Decision Tree

**For code examples and syntax, always consult [better-auth.com/docs](https://better-auth.com/docs).**

Is this a new/empty project?
├─ YES → New project setup
│   1. Identify framework (Next.js, Nuxt, Workers, etc.)
│   2. Choose database (D1, PostgreSQL, MongoDB, MySQL)
│   3. Install better-auth + Drizzle/Kysely
│   4. Create auth.ts + auth-client.ts
│   5. Set up route handler (see Quick Start above)
│   6. Run migrations (Drizzle Kit for D1)
│   7. Add features via plugins (2FA, organizations, etc.)
│
└─ NO → Does project have existing auth?
    ├─ YES → Migration/enhancement
    │   • Audit current auth for gaps
    │   • Plan incremental migration
    │   • See references/framework-comparison.md for migration guides
    │
    └─ NO → Add auth to existing project
        1. Analyze project structure
        2. Install better-auth + adapter
        3. Create auth config (see Quick Start)
        4. Add route handler to existing routes
        5. Run schema migrations
        6. Integrate into existing pages/components

---

Critical Rules

MUST DO

✅ Use `better-auth/minimal` + adapter packages for smallest bundle (v1.5+) ✅ Use `npx auth migrate` and `npx auth generate` for CLI commands (v1.5+) ✅ Set BETTER_AUTH_SECRET via `wrangler secret put` ✅ Configure CORS with `credentials: true` ✅ Match OAuth callback URLs exactly (no trailing slash) ✅ Apply migrations to local D1 before `wrangler d