better-auth-core

Better Auth 核心（TypeScript）

目标

• 使用环境变量和数据层连接配置 Better Auth 实例。
• 接入服务端处理程序和客户端实例。
• 安全地使用会话和服务端 API 方法。
• 保持数据层选项可插拔（驱动或适配器）。

快速开始

1. 安装 better-auth。
2. 设置 BETTER_AUTH_SECRET（32 个字符以上）和 BETTER_AUTH_URL。
3. 创建 auth.ts 并导出 auth。
4. 提供 database（驱动或适配器），或者省略该项以使用无状态会话。
5. 挂载处理程序（auth.handler 或框架辅助函数）。
6. 使用 createAuthClient 创建客户端。

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  database: myDatabaseOrAdapter, // driver or adapter; omit for stateless mode
  emailAndPassword: { enabled: true },
  socialProviders: {
    github: {
      clientId: process.env.GITHUB_CLIENT_ID as string,
      clientSecret: process.env.GITHUB_CLIENT_SECRET as string,
    },
  },
});

核心配置清单

• 将实例导出为 auth（或默认导出），以便辅助函数找到它。
• 确保 BETTER_AUTH_URL 与公开基础 URL 保持一致。
• 如果更改 /api/auth 基础路径，请向客户端传入完整的基础 URL。
• 启用需要数据表的插件前，先添加数据库迁移。

服务端 API 用法

• 通过 auth.api.* 调用服务端端点，并传入 { body, headers, query }。
• 如果需要 Response 对象，请使用 asResponse: true。
• 使用 returnHeaders: true 访问 Set-Cookie 标头。

import { auth } from "./auth";

const session = await auth.api.getSession({
  headers: request.headers,
});

const response = await auth.api.signInEmail({
  body: { email, password },
  asResponse: true,
});

会话访问

• 客户端：authClient.useSession() 或 authClient.getSession()。
• 服务端：auth.api.getSession({ headers })。

TypeScript 提示

• 使用 auth.$Infer 和 authClient.$Infer 推断类型。
• 扩展用户架构时，在客户端使用 inferAdditionalFields。

参考资料

• toolchains/platforms/auth/better-auth/better-auth-core/references/setup-database.md
• toolchains/platforms/auth/better-auth/better-auth-core/references/client-server.md
• toolchains/platforms/auth/better-auth/better-auth-core/references/typescript.md