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.
<plugin> below stands for a plugin from Better Auth's plugin docs.
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.tspnpm --filter web exec void db generate # writes the migrationpnpm --filter web exec void db migrateReview 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:
- 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. tooling/scripts/src/auth-schema.mjsfixes that file so Void can use it:- Tables import from
void/schema-pginstead ofdrizzle-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 indb/schema.tsunder your own name (userPostsRelations = relations(user, …)); Drizzle merges it with the kit's. Never reuse a name fromauth-schema.ts: your export would hide the kit's. - Ids default to a UUIDv7 made in the app (
$defaultFn(uuidv7)fromuuid) instead of Postgres'sgen_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 inRANDOM_ID_TABLES. - A header marks the file as generated.
- Tables import from
vp fmtformats 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_FIELDSinpackages/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-usertakesnameonly, and the sign-up and email-code sign-in endpoints refuseimageand unknown fields (packages/better-auth/src/profile-policy.ts). Set them from server code withauth.api.updateUser. A plugin that creates users with a client-sent name adds its path toNAME_ENDPOINTSthere, so the name rule (parseUserNamein@kit/better-auth/profile-rules) applies. - New callback or redirect fields are checked by
packages/better-auth/src/callback-policy.ts; add their names toCALLBACK_FIELDSif 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.tsdoes. - 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_PATHSinpackages/better-auth/src/two-factor.ts, and a case totwo-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 itspluginsoption (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
rateLimitRulesif 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.