Introduction
Community plugins for better-auth that look and feel like the built-in ones.
better-auth-plugins is a collection of community plugins for
better-auth. Each plugin is a small, opt-in
package that you add to your auth config the same way as better-auth's own
plugins, such as username, organization, or admin.
Why these plugins
They are built for a real product that needed them: a waitlist before launch, referral rewards, an audit log, gaming sign-ins, and a blocklist against throwaway accounts. Instead of keeping that code inside one app, each piece is a plugin you can use too.
Plugins
Audit log
A log of sign-ins, failed sign-ins, account changes, and admin actions. Users see their own history, admins everyone's.
Authentication
Sign in with Steam, Epic Games, and Xbox through better-auth's own signIn.social, like any built-in social provider.
Blocklist
Block disposable email domains, reserved usernames, unwanted organization and team names, weak passwords, and IP addresses or countries. Includes ready-made lists.
Referral
Referral codes, attribution for every sign-up method, and steps such as a first purchase before a referral earns a reward.
Security alerts
Tell users about sign-ins from new devices and changes to their password, email, passkeys, two-factor, linked accounts, and API keys, with a link to lock an intruder out.
Waitlist
Gate sign-up behind a waitlist with double opt-in. Admins approve entries, approved emails get an invite, and only they can create an account.
How a plugin is set up
Every plugin is installed the same way. Using the blocklist as an example:
Install the package
npm install @checodo/better-auth-blocklistEach plugin is its own package under the @checodo scope, so you only
install what you use. better-auth and @better-auth/core are peer
dependencies.
Add the server plugin
import { betterAuth } from "better-auth";
import { blocklist } from "@checodo/better-auth-blocklist";
export const auth = betterAuth({
plugins: [blocklist({ username: { values: ["admin"] } })],
});Add the client plugin
import { createAuthClient } from "better-auth/client";
import { blocklistClient } from "@checodo/better-auth-blocklist/client";
export const authClient = createAuthClient({
plugins: [blocklistClient()],
});The client infers the plugin's endpoints from the server plugin, so calls
like authClient.blocklist.listRules() are fully typed.
Migrate the database
Plugins that store data declare their tables like built-in plugins do, so the better-auth CLI picks them up:
npx auth@latest migrateWhat every plugin gives you
- Typed options and endpoints, on the server and the client, with editor docs for every option.
- Error codes you can check against, exported by each plugin (for
example
BLOCKLIST_ERROR_CODES), with the same{ code, message }responses as better-auth's own errors. - Database tables through better-auth's schema system, so migrations, custom table and field names, and every database adapter work.
- OpenAPI metadata for every endpoint, shown by better-auth's
openAPIplugin. - Tests against a real better-auth instance, and a docs page with every option.
Guides
- Combining plugins: all plugins in one config, how they work together, and which of better-auth's plugins each one is tested with.
- Database: the tables each plugin adds, and the personal data they hold.
- FAQ.
Requirements
better-authand@better-auth/core1.7.20 or a later 1.x release.- ESM. The packages ship ES modules with TypeScript types.
- Any runtime better-auth runs on (Node.js, Bun, Deno, edge): the plugins use Web APIs only.
Contributing
Ideas, bug reports, and new plugins are welcome once the repository is public. Its contributing guide covers the development setup and the conventions every plugin follows.