Better-Auth：适用于Cloudflare Workers的现代化身份验证库，支持Drizzle ORM和Kysely

better-auth by secondsky/claude-skills

80 周安装量

90 GitHub Stars

GitHub

安装命令

npx skills add https://github.com/secondsky/claude-skills --skill better-auth

开发云服务安全

🇨🇳中文介绍

better-auth

状态：生产就绪 最后更新：2025-12-26 包：better-auth@1.4.9（仅支持ESM） 依赖项：Drizzle ORM 或 Kysely（D1必需）

快速开始（5分钟）

安装

选项1：Drizzle ORM（推荐）

bun add better-auth drizzle-orm drizzle-kit

选项2：Kysely

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

⚠️ v1.4.0+ 要求

better-auth v1.4.0+ 仅支持ESM。请确保：

package.json：

{
  "type": "module"
}

从 v1.3.x 升级？ 加载 references/migration-guide-1.4.0.md

广告位招租

在这里展示您的产品或服务

触达数万 AI 开发者，精准高效

联系我们

⚠️ 关键：D1适配器要求

better-auth 没有直接的 d1Adapter()。您必须使用以下之一：

Drizzle ORM（推荐）- drizzleAdapter()
Kysely（替代方案）- 使用带有 D1Dialect 的 Kysely 实例

// ❌ 错误 - 这个不存在

import { d1Adapter } from 'better-auth/adapters/d1'

// ✅ 正确 - 使用 Drizzle
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { drizzle } from 'drizzle-orm/d1'

最小化设置（Cloudflare Workers + Drizzle）

1. 创建 D1 数据库：

wrangler d1 create my-app-db

2. 定义模式（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(),
});

// 完整模式请参见 references/database-schema.ts

3. 初始化认证（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. 创建 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;

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

关于代码示例和语法，请始终查阅 better-auth.com/docs。

这是一个新的/空项目吗？
├─ 是 → 新项目设置
│   1. 确定框架（Next.js、Nuxt、Workers 等）
│   2. 选择数据库（D1、PostgreSQL、MongoDB、MySQL）
│   3. 安装 better-auth + Drizzle/Kysely
│   4. 创建 auth.ts + auth-client.ts
│   5. 设置路由处理器（参见上面的快速开始）
│   6. 运行迁移（D1 使用 Drizzle Kit）
│   7. 通过插件添加功能（2FA、组织等）
│
└─ 否 → 项目已有认证系统吗？
    ├─ 是 → 迁移/增强
    │   • 审计当前认证系统的不足
    │   • 规划增量迁移
    │   • 迁移指南请参见 references/framework-comparison.md
    │
    └─ 否 → 为现有项目添加认证
        1. 分析项目结构
        2. 安装 better-auth + 适配器
        3. 创建认证配置（参见快速开始）
        4. 将路由处理器添加到现有路由
        5. 运行模式迁移
        6. 集成到现有页面/组件中

✅ 使用 Drizzle/Kysely 适配器（d1Adapter 不存在） ✅ 使用 Drizzle Kit 进行迁移（不是 better-auth migrate） ✅ 通过 wrangler secret put 设置 BETTER_AUTH_SECRET ✅ 配置 CORS 时使用 credentials: true ✅ OAuth 回调 URL 必须完全匹配（不能有尾部斜杠） ✅ 在 wrangler dev 之前将迁移应用到本地 D1 ✅ 在模式中使用 camelCase 列名

❌ 对 D1 使用 d1Adapter 或 better-auth migrate ❌ 忘记 CORS 凭据或 OAuth URL 不匹配 ❌ 使用 snake_case 列而不使用 CamelCasePlugin ❌ 跳过本地迁移或硬编码密钥 ❌ 不实现 sendVerificationEmail

⚠️ v1.4.0+ 破坏性变更

仅支持ESM（不支持 CommonJS）：

// package.json 必需
{ "type": "module" }

API 重命名：

forgetPassword → requestPasswordReset
POST /account-info → GET /account-info

回调函数签名：

// v1.3.x：request 参数
sendVerificationEmail: async ({ user, url, request }) => {}

// v1.4.0+：ctx 参数
sendVerificationEmail: async ({ user, url, ctx }) => {}

从 <1.4.0 升级时加载 references/migration-guide-1.4.0.md

v1.4.4-1.4.8 新增功能

自 v1.4.3 以来的关键新增功能：

后台任务（v1.4.8）：全局 backgroundTasks 配置，用于延迟邮件发送
新的 OAuth 提供商：Patreon（v1.4.8）、Vercel（v1.4.3）、Kick（v1.4.6），支持刷新令牌
OAuth 2.1 插件（v1.4.8）：符合标准的 OAuth 实现
CLI 工具（v1.4.4）：better-auth CLI，包含项目脚手架
SAML/SSO：时钟偏差验证（v1.4.7）、InResponseTo、OIDC 发现
管理员权限（v1.4.7）：管理员角色，具有细粒度的用户更新权限
ctx.isTrustedDomain（v1.4.6）：用于域名验证的辅助函数

详细实现指南请加载 references/v1.4-features.md。

变量	用途	示例
`BETTER_AUTH_SECRET`	加密密钥（最少 32 个字符）	生成：`openssl rand -base64 32`
`BETTER_AUTH_URL`	基础 URL	`https://example.com` 或 `http://localhost:8787`
`DATABASE_URL`	数据库连接（D1 可选）	PostgreSQL/MySQL 连接字符串

注意：如果未设置环境变量，仅在配置中定义 baseURL/secret。

命令	用途
`npx @better-auth/cli@latest migrate`	应用模式（仅限内置 Kysely 适配器）
`npx @better-auth/cli@latest generate`	为 Prisma/Drizzle 生成模式
`bunx drizzle-kit generate`	D1：使用此命令生成 Drizzle 迁移
`wrangler d1 migrations apply DB_NAME`	D1：使用此命令应用迁移

添加/更改插件后重新运行。

选项	说明
`appName`	可选的显示名称
`baseURL`	仅当未设置 `BETTER_AUTH_URL` 时
`basePath`	默认 `/api/auth`。设置为 `/` 表示根路径。
`secret`	仅当未设置 `BETTER_AUTH_SECRET` 时（最少 32 个字符）
`database`	必需用于大多数功能。D1 使用 `drizzleAdapter()` 或 Kysely
`secondaryStorage`	用于会话和速率限制的 Redis/KV
`emailAndPassword`	`{ enabled: true }` 以激活
`socialProviders`	`{ google: { clientId, clientSecret }, ... }`
`plugins`	插件数组（从专用路径导入）
`trustedOrigins`	跨域请求的 CSRF 白名单

从专用路径导入以实现 tree-shaking：

import { twoFactor } from "better-auth/plugins/two-factor"
import { organization } from "better-auth/plugins/organization"
import { passkey } from "@better-auth/passkey"  // 独立包

不要使用 from "better-auth/plugins"。

前 5 大错误（所有 15 个错误请参见 references/error-catalog.md）

错误 #1："d1Adapter is not exported"

问题：尝试使用不存在的 d1Adapter 解决方案：改用 drizzleAdapter 或 Kysely（参见上面的快速开始）

错误 #2：模式生成失败

问题：better-auth migrate 对 D1 无效 解决方案：使用 bunx drizzle-kit generate，然后使用 wrangler d1 migrations apply

错误 #3：CamelCase 与 snake_case 不匹配

问题：数据库使用 email_verified 但 better-auth 期望 emailVerified 解决方案：在模式中使用 camelCase 或在 Kysely 中添加 CamelCasePlugin

错误 #4：CORS 错误

问题：Access-Control-Allow-Origin 错误，Cookie 未发送 解决方案：配置 CORS 时使用 credentials: true 和正确的来源

错误 #5：OAuth 重定向 URI 不匹配

问题：社交登录失败，提示 "redirect_uri_mismatch" 解决方案：确保完全匹配：https://yourdomain.com/api/auth/callback/google

所有 15 个错误的详细解决方案请加载 references/error-catalog.md。

用例 1：邮箱/密码认证

何时使用：无需社交提供商的基本认证 快速模式：

// 客户端
await authClient.signIn.email({
  email: "user@example.com",
  password: "password123",
});

// 服务器端 - 在配置中启用
emailAndPassword: {
  enabled: true,
  requireEmailVerification: true,
}

加载：references/setup-guide.md → 第 5 步

用例 2：社交认证（45+ 个提供商）

何时使用：允许用户使用社交账户登录支持：Google、GitHub、Microsoft、Apple、Discord、TikTok、Twitch、Spotify、LinkedIn、Slack、Reddit、Facebook、Twitter/X、Patreon、Vercel、Kick 等 30 多个。 快速模式：

// 客户端
await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

// 服务器配置
socialProviders: {
  google: {
    clientId: env.GOOGLE_CLIENT_ID,
    clientSecret: env.GOOGLE_CLIENT_SECRET,
    scope: ["openid", "email", "profile"],
  },
}

加载：references/setup-guide.md → 第 5 步

用例 3：受保护的 API 路由

何时使用：需要验证用户是否已认证 快速模式：

app.get("/api/protected", async (c) => {
  const auth = createAuth(c.env);
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  return c.json({ data: "protected", user: session.user });
});

加载：references/cloudflare-worker-drizzle.ts

用例 4：多租户与组织

何时使用：构建具有团队/组织的 SaaS 加载：references/advanced-features.md → 组织与团队

用例 5：双因素认证

何时使用：需要使用 2FA/TOTP 增强安全性加载：references/advanced-features.md → 双因素认证

何时加载参考文档

当出现以下情况时加载 references/setup-guide.md：

用户需要完整的 8 步设置教程
用户询问 Kysely 适配器替代方案
用户需要迁移或部署帮助
用户询问 wrangler.toml 配置

当出现以下情况时加载 references/error-catalog.md：

遇到 12 个已记录错误中的任何一个
用户报告 D1 适配器、模式、CORS 或 OAuth 问题
用户询问故障排除或调试
用户需要预防清单

当出现以下情况时加载 references/advanced-features.md：

用户询问 2FA、通行密钥或魔法链接
用户需要组织、团队或 RBAC
用户询问速率限制或会话管理
用户需要从 Clerk 或 Auth.js 迁移的指南
用户需要安全最佳实践或性能优化

当出现以下情况时加载 references/cloudflare-worker-drizzle.ts：

用户需要完整的 Worker 实现示例
用户询问生产就绪的代码
用户希望查看带有受保护路由的完整认证流程

当出现以下情况时加载 references/cloudflare-worker-kysely.ts：

用户更喜欢 Kysely 而不是 Drizzle
用户询问 Kysely 特定的实现

当出现以下情况时加载 references/database-schema.ts：

用户需要包含所有表的完整 better-auth 模式
用户询问自定义表或模式扩展
用户需要数据库的 TypeScript 类型

当出现以下情况时加载 references/react-client-hooks.tsx：

用户构建 React/Next.js 前端
用户需要登录表单、会话钩子或受保护路由
用户询问客户端实现

当出现以下情况时加载 references/configuration-guide.md：

用户询问生产配置
用户需要环境变量设置或 wrangler.toml
用户询问会话配置或 ESM 设置
用户需要 CORS 配置、速率限制或 API 密钥
用户询问配置问题故障排除

当出现以下情况时加载 references/framework-comparison.md：

用户询问 "better-auth vs Clerk" 或 "vs Auth.js"
用户需要帮助选择认证框架
用户需要功能比较、迁移建议或成本分析
用户询问 v1.4.0+ 新功能（数据库连接、无状态会话）

当出现以下情况时加载 references/migration-guide-1.4.0.md：

用户从 better-auth <1.4.0 升级到 1.4.0+
用户遇到 forgetPassword 错误或 ESM 问题
用户询问破坏性变更或迁移步骤
用户需要迁移回调函数或 API 端点

当出现以下情况时加载 references/v1.4-features.md：

用户询问后台任务或延迟邮件发送
用户需要 Patreon、Vercel 或 Kick OAuth 提供商设置
用户询问 OAuth 2.1 合规性
用户需要带有时钟偏差或 OIDC 发现的 SAML/SSO
用户询问 better-auth CLI 工具
用户需要管理员角色权限配置
用户询问 ctx.isTrustedDomain 或域名验证

当出现以下情况时加载 references/nextjs/README.md：

用户使用 PostgreSQL（非 Cloudflare D1）构建 Next.js 应用
用户需要组织和 2FA 示例
用户询问 Next.js 特定的实现

当出现以下情况时加载 references/nextjs/postgres-example.ts：

用户需要完整的 Next.js API 路由实现
用户希望查看组织 + 2FA 的实际应用
用户询问使用 Drizzle 的 PostgreSQL 设置

当出现以下情况时加载 references/frameworks/nextjs.md：

用户使用 Next.js（App Router 或 Pages Router）构建
用户需要中间件、服务器组件或 API 路由

当出现以下情况时加载 references/frameworks/nuxt.md：

用户使用 Nuxt 3 构建
用户需要 H3 处理器、组合函数或服务器路由

当出现以下情况时加载 references/frameworks/remix.md：

用户使用 Remix 构建
用户需要 loader/action 模式或会话处理

当出现以下情况时加载 references/frameworks/sveltekit.md：

用户使用 SvelteKit 构建
用户需要钩子、加载函数或存储

当出现以下情况时加载 references/frameworks/api-frameworks.md：

用户使用 Express、Fastify、NestJS 或 Hono（非 Cloudflare）构建
用户需要中间件或路由配置

当出现以下情况时加载 references/frameworks/expo-mobile.md：

用户构建 React Native 或 Expo 应用
用户需要 SecureStore、深度链接或移动端认证

当出现以下情况时加载 references/databases/postgresql.md：

用户使用 PostgreSQL 与 Drizzle 或 Prisma
用户需要 Neon、Supabase 或连接池设置

当出现以下情况时加载 references/databases/mongodb.md：

用户使用 MongoDB
用户需要 Atlas 设置或索引

当出现以下情况时加载 references/databases/mysql.md：

用户使用 MySQL 或 PlanetScale
用户需要 Vitess 兼容性指导

当出现以下情况时加载 references/plugins/authentication.md：

用户需要 2FA、通行密钥、魔法链接、邮箱 OTP 或匿名用户
用户询问增强的认证方法

当出现以下情况时加载 references/plugins/enterprise.md：

用户需要组织、SSO/SAML、SCIM 或管理仪表板
用户构建多租户或企业应用

当出现以下情况时加载 references/plugins/api-tokens.md：

用户需要 API 密钥、Bearer 令牌、JWT 或 OIDC 提供商
用户为第三方构建 API 认证

当出现以下情况时加载 references/plugins/payments.md：

用户需要 Stripe 或 Polar 集成
用户构建订阅或支付功能

快速配置（v1.4.0+ 仅支持ESM）：

export const auth = betterAuth({
  baseURL: env.BETTER_AUTH_URL,
  secret: env.BETTER_AUTH_SECRET,
  database: drizzleAdapter(db, { provider: "sqlite" }),
});

以下情况请加载 references/configuration-guide.md：

带有邮箱/密码和社交提供商的生产配置
wrangler.toml 设置和环境变量
会话配置、CORS 设置和 ESM 要求
速率限制、API 密钥（v1.4.0+）和故障排除

参考文档（references/）

setup-guide.md - 完整的 8 步设置（D1 → Drizzle → 部署）
error-catalog.md - 所有 12 个错误及其解决方案和预防清单
advanced-features.md - 2FA、组织、速率限制、通行密钥、魔法链接、迁移
configuration-guide.md - 生产配置、环境变量、CORS、速率限制
framework-comparison.md - better-auth vs Clerk vs Auth.js、迁移路径、总拥有成本
migration-guide-1.4.0.md - 从 v1.3.x 升级到 v1.4.0+（ESM、API 变更）
cloudflare-worker-drizzle.ts - 使用 Drizzle 认证的完整 Worker
cloudflare-worker-kysely.ts - 使用 Kysely 认证的完整 Worker
database-schema.ts - 完整的 better-auth Drizzle 模式
react-client-hooks.tsx - 带有认证钩子的 React 组件
v1.4-features.md - 后台任务、新的 OAuth 提供商、SAML/SSO、CLI

框架参考（references/frameworks/）

nextjs.md - Next.js App/Pages Router 集成
nuxt.md - 带有 H3 和组合函数的 Nuxt 3
remix.md - Remix loader、action、会话
sveltekit.md - SvelteKit 钩子和存储
api-frameworks.md - Express、Fastify、NestJS、Hono
expo-mobile.md - React Native 和 Expo

数据库参考（references/databases/）

postgresql.md - 使用 Drizzle/Prisma 的 PostgreSQL、Neon/Supabase
mongodb.md - MongoDB 适配器和 Atlas
mysql.md - MySQL 和 PlanetScale

插件参考（references/plugins/）

authentication.md - 2FA、通行密钥、魔法链接、邮箱 OTP、匿名
enterprise.md - 组织、SSO、SCIM、管理
api-tokens.md - API 密钥、Bearer 令牌、JWT、OIDC
payments.md - Stripe、Polar 集成

Next.js 示例（references/nextjs/）

README.md - Next.js + PostgreSQL 设置指南（非 D1）
postgres-example.ts - 包含组织、2FA、邮箱验证的完整 API 路由

创建认证客户端（src/lib/auth-client.ts）：

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_API_URL || "http://localhost:8787",
});

在 React 中使用：

import { authClient } from "@/lib/auth-client";

export function UserProfile() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return <div>加载中...</div>;
  if (!session) return <div>未认证</div>;

  return (
    <div>
      <p>欢迎，{session.user.email}</p>
      <button onClick={() => authClient.signOut()}>退出登录</button>
    </div>
  );
}

better-auth@^1.4.9 - 核心认证框架（仅支持ESM）

选择一种适配器：

drizzle-orm@^0.44.7 + drizzle-kit@^0.31.7（推荐）
kysely@^0.28.8 + @noxharmonium/kysely-d1@^0.4.0（替代方案）

@cloudflare/workers-types - Workers 的 TypeScript 类型
hono@^4.0.0 - 用于路由的 Web 框架
@better-auth/passkey - 通行密钥插件（v1.4.0+，独立包）
@better-auth/api-key - API 密钥认证（v1.4.0+）

超越 Cloudflare D1

本技能专注于 Cloudflare Workers + D1。better-auth 还支持：

框架（共 18 个）：Next.js、Nuxt、Remix、SvelteKit、Astro、Express、NestJS、Fastify、Elysia、Expo 等。

数据库（9 个适配器）：PostgreSQL、MongoDB、MySQL、Prisma、MS SQL 等。

额外插件：匿名认证、邮箱 OTP、JWT、多会话、OIDC 提供商、支付集成（Stripe、Polar）。

对于非 Cloudflare 设置，请加载相应的框架或数据库参考文件，或查阅官方文档：https://better-auth.com/docs

以下情况请加载 references/framework-comparison.md：

完整功能比较：better-auth vs Clerk vs Auth.js
v1.4.0+ 新功能（数据库连接、无状态会话、API 密钥）
迁移路径、成本分析和性能基准
按用例推荐和 5 年总拥有成本

已验证可用的仓库（全部使用 Drizzle 或 Kysely）：

zwily/example-react-router-cloudflare-d1-drizzle-better-auth - Drizzle
matthewlynch/better-auth-react-router-cloudflare-d1 - Kysely
foxlau/react-router-v7-better-auth - Drizzle
zpg6/better-auth-cloudflare - Drizzle（包含 CLI）

注意：检查每个仓库的 better-auth 版本。使用 v1.3.x 的仓库需要升级到 v1.4.0+（参见 references/migration-guide-1.4.0.md）。没有仓库使用直接的 d1Adapter - 全部需要 Drizzle/Kysely。

已验证 ESM 支持（package.json 中的 "type": "module"）- v1.4.0+ 必需
已安装 better-auth@1.4.9+ + Drizzle 或 Kysely
已使用 wrangler 创建 D1 数据库
已定义包含必需表（user、session、account、verification）的数据库模式
已生成并将迁移应用到 D1
已设置 BETTER_AUTH_SECRET 环境变量
已在认证配置中配置 baseURL
已启用认证方法（emailAndPassword、socialProviders）
已配置 CORS，使用 credentials: true
已在提供商设置中设置 OAuth 回调 URL
已测试认证路由（/api/auth/*）
已测试登录、注册、会话验证
使用 requestPasswordReset（非 forgetPassword）- v1.4.0+ API
已部署到 Cloudflare Workers

有问题？遇到问题？

检查 references/error-catalog.md 获取所有 15 个错误及其解决方案
查看 references/setup-guide.md 获取完整的 8 步设置
参见 references/advanced-features.md 获取 2FA、组织等更多信息
查看官方文档：https://better-auth.com
确保您使用的是 Drizzle 或 Kysely（而非不存在的 d1Adapter）

🇺🇸English

better-auth

Status : Production Ready Last Updated : 2025-12-26 Package : better-auth@1.4.9 (ESM-only) Dependencies : Drizzle ORM or Kysely (required for D1)

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

⚠️ CRITICAL: D1 Adapter Requirements

better-auth DOES NOT have a direct d1Adapter(). You MUST use either:

Drizzle ORM (recommended) - drizzleAdapter()
Kysely (alternative) - Kysely instance with D1Dialect

// ❌ WRONG - This doesn't exist

import { d1Adapter } from 'better-auth/adapters/d1'

// ✅ CORRECT - Use Drizzle
import { drizzleAdapter } from 'better-auth/adapters/drizzle'
import { drizzle } from 'drizzle-orm/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 consultbetter-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 Drizzle/Kysely adapter (d1Adapter doesn't exist) ✅ Use Drizzle Kit for migrations (not better-auth migrate) ✅ 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 dev ✅ Use camelCase column names in schema

NEVER DO

❌ Use d1Adapter or better-auth migrate with D1 ❌ Forget CORS credentials or mismatch OAuth URLs ❌ Use snake_case columns without CamelCasePlugin ❌ Skip local migrations or hardcode secrets ❌ Leave sendVerificationEmail unimplemented

⚠️ v1.4.0+ Breaking Changes

ESM-only (no CommonJS):

// package.json required
{ "type": "module" }

API Renames :

forgetPassword → requestPasswordReset
POST /account-info → GET /account-info

Callback Signatures :

// v1.3.x: request parameter
sendVerificationEmail: async ({ user, url, request }) => {}

// v1.4.0+: ctx parameter
sendVerificationEmail: async ({ user, url, ctx }) => {}

Loadreferences/migration-guide-1.4.0.md when upgrading from <1.4.0

New in v1.4.4-1.4.8

Key additions since v1.4.3 :

Background Tasks (v1.4.8): Global backgroundTasks config to defer email sending
New OAuth Providers : Patreon (v1.4.8), Vercel (v1.4.3), Kick (v1.4.6) with refresh tokens
OAuth 2.1 Plugin (v1.4.8): Standards-compliant OAuth implementation
CLI Tool (v1.4.4): better-auth CLI with project scaffolding
SAML/SSO : Clock skew validation (v1.4.7), InResponseTo, OIDC discovery
Admin Permissions (v1.4.7): Admin role with granular user update permissions
ctx.isTrustedDomain (v1.4.6): Helper for domain verification

Loadreferences/v1.4-features.md for detailed implementation guides.

Quick Reference

Environment Variables

Variable	Purpose	Example
`BETTER_AUTH_SECRET`	Encryption secret (min 32 chars)	Generate: `openssl rand -base64 32`
`BETTER_AUTH_URL`	Base URL	`https://example.com` or `http://localhost:8787`
`DATABASE_URL`	Database connection (optional for D1)	PostgreSQL/MySQL connection string

Note : Only define baseURL/secret in config if env vars are NOT set.

CLI Commands

Command	Purpose
`npx @better-auth/cli@latest migrate`	Apply schema (built-in Kysely adapter only)
`npx @better-auth/cli@latest generate`	Generate schema for Prisma/Drizzle
`bunx drizzle-kit generate`	D1: Use this to generate Drizzle migrations
`wrangler d1 migrations apply DB_NAME`	D1: Use this to apply migrations

Re-run after adding/changing plugins.

Core Config Options

Option	Notes
`appName`	Optional display name
`baseURL`	Only if `BETTER_AUTH_URL` not set
`basePath`	Default `/api/auth`. Set `/` for root.
`secret`	Only if `BETTER_AUTH_SECRET` not set (min 32 chars)

Common Plugins

Import from dedicated paths for tree-shaking:

import { twoFactor } from "better-auth/plugins/two-factor"
import { organization } from "better-auth/plugins/organization"
import { passkey } from "@better-auth/passkey"  // Separate package

NOT from "better-auth/plugins".

Top 5 Errors (See references/error-catalog.md for all 15)

Error #1: "d1Adapter is not exported"

Problem : Trying to use non-existent d1Adapter Solution : Use drizzleAdapter or Kysely instead (see Quick Start above)

Error #2: Schema Generation Fails

Problem : better-auth migrate doesn't work with D1 Solution : Use bunx drizzle-kit generate then wrangler d1 migrations apply

Error #3: CamelCase vs snake_case Mismatch

Problem : Database uses email_verified but better-auth expects emailVerified Solution : Use camelCase in schema or add CamelCasePlugin to Kysely

Error #4: CORS Errors

Problem : Access-Control-Allow-Origin errors, cookies not sent Solution : Configure CORS with credentials: true and correct origins

Error #5: OAuth Redirect URI Mismatch

Problem : Social sign-in fails with "redirect_uri_mismatch" Solution : Ensure exact match: https://yourdomain.com/api/auth/callback/google

Loadreferences/error-catalog.md for all 15 errors with detailed solutions.

Common Use Cases

Use Case 1: Email/Password Authentication

When : Basic authentication without social providers Quick Pattern :

// Client
await authClient.signIn.email({
  email: "user@example.com",
  password: "password123",
});

// Server - enable in config
emailAndPassword: {
  enabled: true,
  requireEmailVerification: true,
}

Load : references/setup-guide.md → Step 5

Use Case 2: Social Authentication (45+ Providers)

When : Allow users to sign in with social accounts Supported : Google, GitHub, Microsoft, Apple, Discord, TikTok, Twitch, Spotify, LinkedIn, Slack, Reddit, Facebook, Twitter/X, Patreon, Vercel, Kick, and 30+ more. Quick Pattern :

// Client
await authClient.signIn.social({
  provider: "google",
  callbackURL: "/dashboard",
});

// Server config
socialProviders: {
  google: {
    clientId: env.GOOGLE_CLIENT_ID,
    clientSecret: env.GOOGLE_CLIENT_SECRET,
    scope: ["openid", "email", "profile"],
  },
}

Load : references/setup-guide.md → Step 5

Use Case 3: Protected API Routes

When : Need to verify user is authenticated Quick Pattern :

app.get("/api/protected", async (c) => {
  const auth = createAuth(c.env);
  const session = await auth.api.getSession({
    headers: c.req.raw.headers,
  });

  if (!session) {
    return c.json({ error: "Unauthorized" }, 401);
  }

  return c.json({ data: "protected", user: session.user });
});

Load : references/cloudflare-worker-drizzle.ts

Use Case 4: Multi-Tenant with Organizations

When : Building SaaS with teams/organizations Load : references/advanced-features.md → Organizations & Teams

Use Case 5: Two-Factor Authentication

When : Need extra security with 2FA/TOTP Load : references/advanced-features.md → Two-Factor Authentication

When to Load References

Loadreferences/setup-guide.md when:

User needs complete 8-step setup walkthrough
User asks about Kysely adapter alternative
User needs help with migrations or deployment
User asks about wrangler.toml configuration

Loadreferences/error-catalog.md when:

Encountering any of the 12 documented errors
User reports D1 adapter, schema, CORS, or OAuth issues
User asks about troubleshooting or debugging
User needs prevention checklist

Loadreferences/advanced-features.md when:

User asks about 2FA, passkeys, or magic links
User needs organizations, teams, or RBAC
User asks about rate limiting or session management
User wants migration guide from Clerk or Auth.js
User needs security best practices or performance optimization

Loadreferences/cloudflare-worker-drizzle.ts when:

User needs complete Worker implementation example
User asks for production-ready code
User wants to see full auth flow with protected routes

Loadreferences/cloudflare-worker-kysely.ts when:

User prefers Kysely over Drizzle
User asks for Kysely-specific implementation

Loadreferences/database-schema.ts when:

User needs complete better-auth schema with all tables
User asks about custom tables or schema extension
User needs TypeScript types for database

Loadreferences/react-client-hooks.tsx when:

User building React/Next.js frontend
User needs login forms, session hooks, or protected routes
User asks about client-side implementation

Loadreferences/configuration-guide.md when:

User asks about production configuration
User needs environment variable setup or wrangler.toml
User asks about session configuration or ESM setup
User needs CORS configuration, rate limiting, or API keys
User asks about troubleshooting configuration issues

Loadreferences/framework-comparison.md when:

User asks "better-auth vs Clerk" or "vs Auth.js"
User needs help choosing auth framework
User wants feature comparison, migration advice, or cost analysis
User asks about v1.4.0+ new features (database joins, stateless sessions)

Loadreferences/migration-guide-1.4.0.md when:

User upgrading from better-auth <1.4.0 to 1.4.0+
User encounters forgetPassword errors or ESM issues
User asks about breaking changes or migration steps
User needs to migrate callback functions or API endpoints

Loadreferences/v1.4-features.md when:

User asks about background tasks or deferred email sending
User needs Patreon, Vercel, or Kick OAuth provider setup
User asks about OAuth 2.1 compliance
User needs SAML/SSO with clock skew or OIDC discovery
User asks about the better-auth CLI tool
User needs admin role permissions configuration
User asks about ctx.isTrustedDomain or domain verification

Loadreferences/nextjs/README.md when:

User building Next.js app with PostgreSQL (not Cloudflare D1)
User needs organizations and 2FA example
User asks about Next.js-specific implementation

Loadreferences/nextjs/postgres-example.ts when:

User needs complete Next.js API route implementation
User wants to see organizations + 2FA in practice
User asks for PostgreSQL setup with Drizzle

Framework-Specific Setup

Loadreferences/frameworks/nextjs.md when:

User building with Next.js (App Router or Pages Router)
User needs middleware, Server Components, or API routes

Loadreferences/frameworks/nuxt.md when:

User building with Nuxt 3
User needs H3 handlers, composables, or server routes

Loadreferences/frameworks/remix.md when:

User building with Remix
User needs loader/action patterns or session handling

Loadreferences/frameworks/sveltekit.md when:

User building with SvelteKit
User needs hooks, load functions, or stores

Loadreferences/frameworks/api-frameworks.md when:

User building with Express, Fastify, NestJS, or Hono (non-Cloudflare)
User needs middleware or route configuration

Loadreferences/frameworks/expo-mobile.md when:

User building React Native or Expo app
User needs SecureStore, deep linking, or mobile auth

Database Adapters

Loadreferences/databases/postgresql.md when:

User using PostgreSQL with Drizzle or Prisma
User needs Neon, Supabase, or connection pooling setup

Loadreferences/databases/mongodb.md when:

User using MongoDB
User needs Atlas setup or indexes

Loadreferences/databases/mysql.md when:

User using MySQL or PlanetScale
User needs Vitess compatibility guidance

Plugin Guides

Loadreferences/plugins/authentication.md when:

User needs 2FA, passkeys, magic links, email OTP, or anonymous users
User asks about enhanced authentication methods

Loadreferences/plugins/enterprise.md when:

User needs organizations, SSO/SAML, SCIM, or admin dashboard
User building multi-tenant or enterprise application

Loadreferences/plugins/api-tokens.md when:

User needs API keys, bearer tokens, JWT, or OIDC provider
User building API authentication for third parties

Loadreferences/plugins/payments.md when:

User needs Stripe or Polar integration
User building subscription or payment features

Configuration Reference

Quick Config (ESM-only in v1.4.0+):

export const auth = betterAuth({
  baseURL: env.BETTER_AUTH_URL,
  secret: env.BETTER_AUTH_SECRET,
  database: drizzleAdapter(db, { provider: "sqlite" }),
});

Loadreferences/configuration-guide.md for:

Production configuration with email/password and social providers
wrangler.toml setup and environment variables
Session configuration, CORS setup, and ESM requirements
Rate limiting, API keys (v1.4.0+), and troubleshooting

Using Bundled Resources

References (references/)

setup-guide.md - Complete 8-step setup (D1 → Drizzle → Deploy)
error-catalog.md - All 12 errors with solutions and prevention checklist
advanced-features.md - 2FA, organizations, rate limiting, passkeys, magic links, migrations
configuration-guide.md - Production config, environment variables, CORS, rate limiting
framework-comparison.md - better-auth vs Clerk vs Auth.js, migration paths, TCO
migration-guide-1.4.0.md - Upgrading from v1.3.x to v1.4.0+ (ESM, API changes)
cloudflare-worker-drizzle.ts - Complete Worker with Drizzle auth
cloudflare-worker-kysely.ts - Complete Worker with Kysely auth
database-schema.ts - Complete better-auth Drizzle schema
react-client-hooks.tsx - React components with auth hooks
v1.4-features.md - Background tasks, new OAuth providers, SAML/SSO, CLI

Framework References (references/frameworks/)

nextjs.md - Next.js App/Pages Router integration
nuxt.md - Nuxt 3 with H3 and composables
remix.md - Remix loaders, actions, sessions
sveltekit.md - SvelteKit hooks and stores
api-frameworks.md - Express, Fastify, NestJS, Hono
expo-mobile.md - React Native and Expo

Database References (references/databases/)

postgresql.md - PostgreSQL with Drizzle/Prisma, Neon/Supabase
mongodb.md - MongoDB adapter and Atlas
mysql.md - MySQL and PlanetScale

Plugin References (references/plugins/)

authentication.md - 2FA, passkeys, magic links, email OTP, anonymous
enterprise.md - Organizations, SSO, SCIM, admin
api-tokens.md - API keys, bearer tokens, JWT, OIDC
payments.md - Stripe, Polar integrations

Next.js Examples (references/nextjs/)

README.md - Next.js + PostgreSQL setup guide (not D1)
postgres-example.ts - Complete API route with organizations, 2FA, email verification

Client Integration

Create auth client (src/lib/auth-client.ts):

import { createAuthClient } from "better-auth/client";

export const authClient = createAuthClient({
  baseURL: import.meta.env.VITE_API_URL || "http://localhost:8787",
});

Use in React :

import { authClient } from "@/lib/auth-client";

export function UserProfile() {
  const { data: session, isPending } = authClient.useSession();

  if (isPending) return <div>Loading...</div>;
  if (!session) return <div>Not authenticated</div>;

  return (
    <div>
      <p>Welcome, {session.user.email}</p>
      <button onClick={() => authClient.signOut()}>Sign Out</button>
    </div>
  );
}

Dependencies

Required :

better-auth@^1.4.9 - Core authentication framework (ESM-only)

Choose ONE adapter :

drizzle-orm@^0.44.7 + drizzle-kit@^0.31.7 (recommended)
kysely@^0.28.8 + @noxharmonium/kysely-d1@^0.4.0 (alternative)

Optional :

@cloudflare/workers-types - TypeScript types for Workers
hono@^4.0.0 - Web framework for routing
@better-auth/passkey - Passkey plugin (v1.4.0+, separate package)
@better-auth/api-key - API key auth (v1.4.0+)

Beyond Cloudflare D1

This skill focuses on Cloudflare Workers + D1. better-auth also supports:

Frameworks (18 total): Next.js, Nuxt, Remix, SvelteKit, Astro, Express, NestJS, Fastify, Elysia, Expo, and more.

Databases (9 adapters): PostgreSQL, MongoDB, MySQL, Prisma, MS SQL, and others.

Additional Plugins : Anonymous auth, Email OTP, JWT, Multi-Session, OIDC Provider, payment integrations (Stripe, Polar).

For non-Cloudflare setups , load the appropriate framework or database reference file, or consult the official docs: https://better-auth.com/docs

Official Documentation

better-auth Docs : https://better-auth.com
GitHub : https://github.com/better-auth/better-auth (22.4k ⭐)
Examples : https://github.com/better-auth/better-auth/tree/main/examples
Drizzle Docs : https://orm.drizzle.team/docs/get-started-sqlite
Kysely Docs : https://kysely.dev/
Discord : https://discord.gg/better-auth

Framework Comparison

Loadreferences/framework-comparison.md for:

Complete feature comparison: better-auth vs Clerk vs Auth.js
v1.4.0+ new features (database joins, stateless sessions, API keys)
Migration paths, cost analysis, and performance benchmarks
Recommendations by use case and 5-year TCO

Production Examples

Verified working repositories (all use Drizzle or Kysely):

zwily/example-react-router-cloudflare-d1-drizzle-better-auth - Drizzle
matthewlynch/better-auth-react-router-cloudflare-d1 - Kysely
foxlau/react-router-v7-better-auth - Drizzle
zpg6/better-auth-cloudflare - Drizzle (includes CLI)

Note : Check each repo's better-auth version. Repos on v1.3.x need v1.4.0+ migration (see references/migration-guide-1.4.0.md). None use a direct d1Adapter - all require Drizzle/Kysely.

Complete Setup Checklist

Verified ESM support ("type": "module" in package.json) - v1.4.0+ required
Installed better-auth@1.4.9+ + Drizzle OR Kysely
Created D1 database with wrangler
Defined database schema with required tables (user, session, account, verification)
Generated and applied migrations to D1
Set BETTER_AUTH_SECRET environment variable
Configured baseURL in auth config
Enabled authentication methods (emailAndPassword, socialProviders)
Configured CORS with credentials: true
Set OAuth callback URLs in provider settings
Tested auth routes (/api/auth/*)
Tested sign-in, sign-up, session verification
Using requestPasswordReset (not forgetPassword) - v1.4.0+ API
Deployed to Cloudflare Workers

Questions? Issues?

Check references/error-catalog.md for all 15 errors and solutions
Review references/setup-guide.md for complete 8-step setup
See references/advanced-features.md for 2FA, organizations, and more
Check official docs: https://better-auth.com
Ensure you're using Drizzle or Kysely (not non-existent d1Adapter)

Weekly Installs

Repository

secondsky/claude-skills

GitHub Stars

First Seen

Jan 24, 2026

Security Audits

Gen Agent Trust HubPass SocketPass SnykPass

Installed on

claude-code67

gemini-cli65

codex63

opencode63

cursor61

github-copilot60

Azure RBAC 权限管理工具：查找最小角色、创建自定义角色与自动化分配

142,000 周安装

Better-Auth：适用于Cloudflare Workers的现代化身份验证库，支持Drizzle ORM和Kysely

🇨🇳中文介绍

better-auth

快速开始（5分钟）

安装

⚠️ v1.4.0+ 要求

相关 Skills

⚠️ 关键：D1适配器要求

最小化设置（Cloudflare Workers + Drizzle）

决策树

关键规则

必须做

切勿做

⚠️ v1.4.0+ 破坏性变更

v1.4.4-1.4.8 新增功能

快速参考

环境变量

CLI 命令

核心配置选项

常用插件

前 5 大错误（所有 15 个错误请参见 references/error-catalog.md）

错误 #1："d1Adapter is not exported"

错误 #2：模式生成失败

错误 #3：CamelCase 与 snake_case 不匹配

错误 #4：CORS 错误

错误 #5：OAuth 重定向 URI 不匹配

常见用例

用例 1：邮箱/密码认证

用例 2：社交认证（45+ 个提供商）

用例 3：受保护的 API 路由

用例 4：多租户与组织

用例 5：双因素认证

何时加载参考文档

框架特定设置

数据库适配器

插件指南

配置参考

使用捆绑资源

参考文档（references/）

框架参考（references/frameworks/）

数据库参考（references/databases/）

插件参考（references/plugins/）

Next.js 示例（references/nextjs/）

客户端集成

依赖项

超越 Cloudflare D1

官方文档

框架比较

生产示例

完整设置清单

🇺🇸English

better-auth

Quick Start (5 Minutes)

Installation

⚠️ v1.4.0+ Requirements

⚠️ CRITICAL: D1 Adapter Requirements

Minimal Setup (Cloudflare Workers + Drizzle)

Decision Tree

Critical Rules

MUST DO

NEVER DO

⚠️ v1.4.0+ Breaking Changes

New in v1.4.4-1.4.8

Quick Reference

Environment Variables

CLI Commands

Core Config Options

Common Plugins

Top 5 Errors (See references/error-catalog.md for all 15)

Error #1: "d1Adapter is not exported"

Error #2: Schema Generation Fails

Error #3: CamelCase vs snake_case Mismatch

Error #4: CORS Errors

Error #5: OAuth Redirect URI Mismatch

Common Use Cases

Use Case 1: Email/Password Authentication

Use Case 2: Social Authentication (45+ Providers)

Use Case 3: Protected API Routes

Use Case 4: Multi-Tenant with Organizations

Use Case 5: Two-Factor Authentication