TypeScript

Better Auth 设计为类型安全的。客户端和服务器均使用 TypeScript 构建，允许你轻松推断类型。

TypeScript 配置

严格模式

Better Auth 设计为与 TypeScript 的严格模式配合使用。我们建议在你的 TypeScript 配置文件中启用严格模式：

tsconfig.json

{
  "compilerOptions": {
    "strict": true
  }
}

如果你无法将 strict 设置为 true，你可以启用 strictNullChecks：

tsconfig.json

{
  "compilerOptions": {
    "strictNullChecks": true,
  }
}

当 strict 设置为 true 时，strictNullChecks 也会被启用。如果你显式地将 strictNullChecks 设置为 false，可能会导致类型推断问题。

如果你遇到 TypeScript 推断超过编译器序列化最大长度的问题，请确保你遵循了上述说明，并确保没有同时启用 declaration 和 composite。

类型推断

客户端 SDK 和服务器端都提供可通过 $Infer 属性推断的类型。插件可以扩展基础类型如 User 和 Session，你可以使用 $Infer 来推断这些类型。此外，插件还可以提供额外的类型，也可以通过 $Infer 进行推断。

auth-client.ts

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

const authClient = createAuthClient()

export type Session = typeof authClient.$Infer.Session

Session 类型包含 session 和 user 两个属性。user 属性表示用户对象类型，session 属性表示会话对象类型。

你也可以在服务器端推断类型。

auth.ts

import { betterAuth } from "better-auth"
import Database from "better-sqlite3"

export const auth = betterAuth({
    database: new Database("database.db")
})

type Session = typeof auth.$Infer.Session

额外字段

Better Auth 允许你为用户和会话对象添加额外字段。所有额外字段都会被正确推断，并且在服务器和客户端都可用。

auth.ts

import { betterAuth } from "better-auth"
import Database from "better-sqlite3"

export const auth = betterAuth({
    database: new Database("database.db"),
    user: {
       additionalFields: {
          role: {
              type: "string",
              input: false
            } 
        }
    }
   
})

type Session = typeof auth.$Infer.Session

在上面的示例中，我们向用户对象添加了一个 role 字段。该字段现在可在 Session 类型中使用。

`input` 属性

额外字段配置中的 input 属性决定该字段是否应包含在用户输入中。此属性默认值为 true，意味着字段会成为用户在注册等操作时的输入部分。

若要阻止某字段成为用户输入部分，必须显式设置 input: false：

additionalFields: {
    role: {
        type: "string",
        input: false
    }
}

当 input 设置为 false 时，该字段将被排除在用户输入之外，防止用户传入该字段的值。

默认情况下，额外字段包含在用户输入中，如果处理不当可能带来安全隐患。对于不应由用户设置的字段，如 role，务必在配置中将 input 设置为 false。

在客户端推断额外字段

为了确保客户端正确推断额外字段的类型，你需要告知客户端这些字段。根据项目结构，有两种方法：

对于 Monorepo 或单一项目设置

如果你的服务器和客户端代码在同一个项目中，可以使用 inferAdditionalFields 插件从服务器配置自动推断额外字段。

auth-client.ts

import { inferAdditionalFields } from "better-auth/client/plugins";
import { createAuthClient } from "better-auth/client";
import type { auth } from "@/lib/auth"; // 将 auth 实例作为类型导入

export const authClient = createAuthClient({
  plugins: [inferAdditionalFields<typeof auth>()],
});

对于客户端和服务器分离的项目

如果客户端和服务器在不同项目中，你需要在创建认证客户端时手动指定额外字段。

auth-client.ts

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

export const authClient = createAuthClient({
  plugins: [inferAdditionalFields({
      user: {
        role: {
          type: "string"
        }
      }
  })],
});

TypeScript

TypeScript 配置

严格模式

类型推断

额外字段

input 属性

在客户端推断额外字段

本页目录

`input` 属性