home / skills / bobmatnyc / claude-mpm-skills / better-auth-plugins

better-auth-plugins skill

safe

/toolchains/platforms/auth/better-auth/better-auth-plugins

This skill helps you implement advanced authentication by orchestrating server and client plugins with migrations and schema updates.

npx playbooks add skill bobmatnyc/claude-mpm-skills --skill better-auth-plugins

Review the files below or copy the command above to add this skill to your agents.

Files (3)

SKILL.md

1.9 KB

---
name: better-auth-plugins
description: Better Auth plugin system for TypeScript. Use when adding advanced auth features (2FA, magic link, passkey, username, JWT, organizations) via server and client plugins.
progressive_disclosure:
  entry_point:
    summary: "Better Auth plugin system for TypeScript. Use when adding advanced auth features (2FA, magic link, passkey, username, JWT, organizations) via server and client plugins."
    when_to_use: "When implementing authentication, authorization, or security."
    quick_start: "1. Review the core concepts below. 2. Apply patterns to your use case. 3. Follow best practices for implementation."
  references:
    - plugins-index.md
---
# Better Auth Plugins

## Goals
- Add server plugins to extend auth features.
- Add client plugins for matching client methods.
- Apply schema changes when plugins add tables.

## Quick start
1. Import the plugin from `better-auth/plugins` and add it to `plugins`.
2. Run migrations (`generate` or `migrate`) when required.
3. Add the client plugin from `better-auth/client/plugins`.

### Example: Two-factor authentication
```ts
import { betterAuth } from "better-auth";
import { twoFactor } from "better-auth/plugins";

export const auth = betterAuth({
  plugins: [twoFactor()],
});
```

```ts
import { createAuthClient } from "better-auth/client";
import { twoFactorClient } from "better-auth/client/plugins";

export const authClient = createAuthClient({
  plugins: [twoFactorClient({ twoFactorPage: "/two-factor" })],
});
```

## Migration reminder
Run the CLI when a plugin adds tables:

```bash
npx @better-auth/cli generate
```

```bash
npx @better-auth/cli migrate
```

## Guardrails
- Add server and client plugins together to keep APIs aligned.
- Keep `nextCookies` (if used) last in the server plugin list.
- Review plugin docs for required schema and env variables.

## References
- `toolchains/platforms/auth/better-auth/better-auth-plugins/references/plugins-index.md`

Overview

This skill documents the Better Auth plugin system for TypeScript, designed to add advanced authentication features via server and client plugins. It focuses on extensibility for 2FA, magic links, passkeys, username-based auth, JWTs, and organization-aware workflows. The content highlights how to install plugins, keep server and client APIs aligned, and manage database schema changes through migrations.

How this skill works

Plugins register server-side behavior (routes, middleware, schema) and matching client-side helpers to expose the new auth flows in the browser. When a plugin requires new tables or fields it emits schema changes that must be applied with the CLI generate/migrate commands. The recommendation is to add pairing server and client plugins together so runtime and client APIs stay synchronized.

When to use it

You need to add 2FA, magic links, passkeys, or other advanced auth methods to an app.
You want both server logic and client helpers for a new authentication flow.
A plugin requires new database tables or columns and you can run migrations.
You need organization-aware auth or multi-tenant user features.
You are building a TypeScript app and want modular, composable auth extensions.

Best practices

Always install the server plugin and its corresponding client plugin together to avoid API mismatches.
Run npx @better-auth/cli generate and then migrate whenever a plugin adds schema changes.
Place nextCookies (if used) last in the server plugin list to prevent cookie handling conflicts.
Review each plugin’s docs for required environment variables and schema requirements before deploying.
Test new auth flows end-to-end (registration, login, recovery, 2FA) in a staging environment after migrations.

Example use cases

Enable two-factor authentication by adding the twoFactor server plugin and twoFactorClient with a custom two-factor page.
Implement passwordless login with a magic link plugin on the server and client-side handlers for link acceptance.
Add passkey support while keeping existing username/JWT flows intact by composing multiple plugins.
Introduce organization-scoped user roles and permissions with a plugin that creates org tables and client role helpers.
Migrate an existing app to include session JWT support via a plugin that updates auth tables and client token management.

FAQ

What CLI commands are required when a plugin adds database tables?

Run npx @better-auth/cli generate to create migration files, then npx @better-auth/cli migrate to apply them.

Do I need to add client plugins for every server plugin?

You should add the matching client plugin when available to keep client APIs aligned and provide UX helpers.