Skip to Content
better-auth-plugins

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

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-blocklist

Each 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

auth.ts
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

auth-client.ts
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 migrate

What 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 openAPI plugin.
  • 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-auth and @better-auth/core 1.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.

On this page