# Adding Better Auth Plugins

> How to add a Better Auth plugin to the kit's instance and regenerate the auth tables and migration.

*Canonical: https://makerkit.dev/docs/void-cloudflare/authentication/adding-plugins*

---

Better Auth plugins add endpoints, client methods and often tables. The kit's options are built in one place, so the app, the schema generator and the seed all see the same plugins.

This page is part of the [Authentication documentation](./overview).

{% callout type="note" %}
`<plugin>` below stands for a plugin from [Better Auth's plugin docs](https://www.better-auth.com/docs/plugins).
{% /callout %}

## 1. Add It to the Options

```ts {% title="packages/better-auth/src/options.ts" %}
import { <plugin> } from 'better-auth/plugins';

export function createAuthOptions(deps: AuthDeps) {
  return {
    // …
    plugins: [<plugin>({ /* options */ })],
  } satisfies BetterAuthOptions;
}
```

A plugin owned by another package (billing's Stripe plugin) doesn't go here: that package builds it, and the app passes it as `AuthDeps.plugins` (`authDepsFromConfig({ ..., plugins })` in `apps/web/config/auth.server.ts`). If it has tables, add its schema variant to `authSchemaPlugins` (`apps/web/config/auth-schema-plugins.ts`), which the schema CLI and the seed pass as `placeholderAuthDeps(db, { plugins })`; `auth-schema-plugins.test.ts` fails if its tables differ from the runtime plugin's.

A value that differs per environment (a key, a flag) goes into `AuthDeps`, mapped in `authDepsFromConfig` (`packages/better-auth/src/auth-deps.ts`) and passed from `apps/web/config/auth.server.ts`, which reads `void/env`. Never read `process.env` in the package. A new required `AuthDeps` field also goes into `placeholderAuthDeps` (`packages/better-auth/src/placeholder-deps.ts`, from `@kit/better-auth/options`), which the schema CLI and the seed use (the type check reminds you).

## 2. Add Its Client Plugin

If the plugin has browser methods:

```ts {% title="packages/better-auth/src/client.ts" %}
import { <plugin>Client } from 'better-auth/client/plugins';

export const authClient = createAuthClient({
  fetchOptions: { customFetchImpl: fetchOrNetworkError },
  plugins: [<plugin>Client()],
});
```

## 3. Regenerate the Tables

```bash
pnpm --filter web exec vp run auth:generate   # rewrites apps/web/db/auth-schema.ts
pnpm --filter web exec void db generate       # writes the migration
pnpm --filter web exec void db migrate
```

Review the SQL, then commit `db/auth-schema.ts`, the migration and `void.lock.json`. Never edit `auth-schema.ts` by hand: the next `auth:generate` overwrites it. CI fails when the schema or migrations are out of date.

### What `auth:generate` Does

It runs three steps:

1. The Better Auth CLI writes a Drizzle schema from `apps/web/config/auth.cli.ts`, using the same options as the app with placeholder values.
2. `tooling/scripts/src/auth-schema.mjs` fixes that file so Void can use it:
   - Tables import from `void/schema-pg` instead of `drizzle-orm/pg-core`.
   - The `relations(...)` blocks stay: Better Auth's database joins (`advanced.database.joins`, on in the kit) read them. They are not SQL, so they need no migration. To add a relation to an auth table (a user's posts), declare it in `db/schema.ts` under your own name (`userPostsRelations = relations(user, …)`); Drizzle merges it with the kit's. Never reuse a name from `auth-schema.ts`: your export would hide the kit's.
   - Ids default to a UUIDv7 made in the app (`$defaultFn(uuidv7)` from `uuid`) instead of Postgres's `gen_random_uuid()`, a v4. They sort by creation time, so new rows go at the end of the index. The invitation table keeps a random v4 (`crypto.randomUUID()`), because its id is the invitation link's secret and a v7 shows when it was created. Tables that need random ids are listed in `RANDOM_ID_TABLES`.
   - A header marks the file as generated.
3. `vp fmt` formats it.

The script throws instead of writing a half-fixed file when Better Auth's output changes shape: no `gen_random_uuid()` id defaults (for example if `advanced.database.generateId: 'uuid'` was removed), or an `sql` default it doesn't know. Its tests are in `auth-schema.test.mjs` next to it. Don't set a custom `generateId` function in the Better Auth options: the CLI would then write `text` ids.

## 4. Mind the Hooks and Limits

- **Endpoints that set a password** must pass the password rules. Add the endpoint and its field to `PASSWORD_FIELDS` in `packages/better-auth/src/password-policy.ts`.
- **New user fields** (`user.additionalFields`, a plugin's user columns) are not writable from the browser: over HTTP `/update-user` takes `name` only, and the sign-up and email-code sign-in endpoints refuse `image` and unknown fields (`packages/better-auth/src/profile-policy.ts`). Set them from server code with `auth.api.updateUser`. A plugin that creates users with a client-sent name adds its path to `NAME_ENDPOINTS` there, so the name rule (`parseUserName` in `@kit/better-auth/profile-rules`) applies.
- **New callback or redirect fields** are checked by `packages/better-auth/src/callback-policy.ts`; add their names to `CALLBACK_FIELDS` if the plugin uses other ones.
- **Endpoints you don't use:** a plugin may add more than you need (email OTP also resets passwords and changes emails). Refuse the rest in a before-hook, as `packages/better-auth/src/otp-scope.ts` does.
- **Plugins that sign users in** (a new sign-in method) must be challenged by two-factor authentication: add the path that creates the session to `EXTRA_CHALLENGE_PATHS` in `packages/better-auth/src/two-factor.ts`, and a case to `two-factor.test.ts`. Otherwise users with 2FA on sign in without the code. Passkeys are the one exception, on purpose: a passkey is two factors itself ([Passkeys](./passkeys)).
- **Plugins with tables** are registered in `placeholderAuthDeps` (`packages/better-auth/src/placeholder-deps.ts`, the schema CLI) whatever their flag, so their tables always exist and the flag needs no migration. Other packages' plugins go through its `plugins` option (`authSchemaPlugins`, above).
- **Indexes** a plugin's fields can't declare go in `EXTRA_INDEXES` (`tooling/scripts/src/auth-schema.mjs`).
- **Rate limits:** the plugin keeps its own limits. Add a rule with `rateLimitRules` if you need a different one ([Rate Limits](./rate-limits)).

## 5. Test It

Add a spec under `apps/e2e/tests/auth/` for the user-visible flow. See [Testing](./testing).
