Payload Better Auth Plugin

You are one plugin away from revolutionizing your Payload CMS auth.
Learn more »

Docs · Issues

A plugin that integrates Better Auth with Payload CMS v3, providing enhanced authentication capabilities. This plugin is thought to be used in production, with real users, so to be rock solid well tested and reliable. 🗿

Description

The @b3nab/payload-better-auth plugin wraps the better-auth library to seamlessly integrate advanced authentication features into Payload CMS v3. It enhances developer productivity and user experience by offering more sophisticated authentication methods beyond Payload's built-in auth system. Definitely it's a better-way 🤓 to manage authentication for Payload CMS v3.

Why This Plugin?

While Payload CMS comes with a solid and extensible authentication system out of the box, it primarily focuses on basic email/password authentication and API keys. This serves many use cases well, but modern applications often require more sophisticated authentication methods and features.

Features

The goal is to seamlessly integrate better-auth in your Payload CMS v3 application, providing a robust and feature-rich authentication system with a focus on user experience and developer productivity.

• Basic integration - Out of the box 🤝
  • Integration with Better Auth
  • Automatic Collections creation
  • Automatic Better Auth API Endpoints creation
  • Payload Adapter as Better Auth database, with transactions, joins, and automatic cleanup of dependent records on delete
• Better Integration 🤓
  • 2FA TOTP-based for Admin Panel
  • Social login buttons auto-injected into the admin login screen
  • Default email verification and password reset flows (overridable)
  • Easily extend Collections using Payload-like collection's config
  • payload.betterAuth instance, fully typed with your own plugin options
  • Auth layer helpers for Next.js (checkers, guards)

Installation

Install the plugin and its peer dependencies:

pnpm add @b3nab/payload-better-auth better-auth better-auth-harmony

Quick Start

Create the plugin config in its own file:

// lib/payload-better-auth.config.ts
import { defineBetterAuthPluginOptions } from "@b3nab/payload-better-auth";

export const payloadBetterAuthConfig = defineBetterAuthPluginOptions({
  // Better Auth Config. https://www.better-auth.com/docs/reference/options
  betterAuth: {
    // used by two factor plugin as an issuer and other things
    appName: "My App",
    // better-auth secret - you can omit it if your env variable is named `BETTER_AUTH_SECRET`
    /** you can generate a good secret
     * using the following command:
     * @example
     * openssl rand -base64 32
     */
    secret: process.env.BETTER_AUTH_SECRET,
  },
});

// makes payload.betterAuth fully typed with YOUR options, everywhere
declare module "@b3nab/payload-better-auth" {
  interface PayloadBetterAuthRegister {
    pluginOptions: typeof payloadBetterAuthConfig;
  }
}

Then add the plugin to your payload.config.ts file:

import { buildConfig } from "payload";
import { betterAuthPlugin } from "@b3nab/payload-better-auth";
import { payloadBetterAuthConfig } from "./lib/payload-better-auth.config";

export default buildConfig({
  // ... other config

  plugins: [betterAuthPlugin(payloadBetterAuthConfig)],
  // ... other config
});

See the docs for the full setup: custom collections, roles, social providers, email flows, and protected Next.js routes.

Important Notes

1. This plugin may perform operations that could affect your application and database
2. Maintainers are not responsible for issues that may occur
3. Contributions via issues and PRs are highly encouraged

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'feat: add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Credits

Created and maintained by Benedetto Abbenanti.

This project would not be possible without the following open-source projects:

• Better Auth
• Payload CMS