Adding Better Auth Plugins

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

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.

1. Add It to the Options

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:

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

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).
  • 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).

5. Test It

Add a spec under apps/e2e/tests/auth/ for the user-visible flow. See Testing.