Payload Collections

The plugin builds Payload collections from your Better Auth options at startup. The exact set depends on which Better Auth plugins are active (twoFactor, passkey, admin, ...), but the base set is always present.

Auto-generated collections

Slugs are singular. Any other plugin you add can introduce its own collection(s); they are picked up automatically from getAuthTables(auth.options) (see src/plugin.ts).

Extending a collection

Each value in extendsCollections is a standard Payload CollectionConfig - the same shape you would pass to buildConfig({ collections: [...] }) - with the slug field omitted (since the plugin owns the slug). The exact type is exported:

import type { CollectionSlug, CollectionConfig } from 'payload'

export type CollectionConfigExtend<T extends CollectionSlug> = Omit<
  CollectionConfig<T>,
  'slug'
>

So anything Payload supports - fields, hooks, access, admin, versions, custom components, etc. - works exactly as it does in a normal collection. Inline form:

import { betterAuthPlugin } from '@b3nab/payload-better-auth'

betterAuthPlugin({
  extendsCollections: {
    user: {
      admin: { useAsTitle: 'email' },
      fields: [
        { name: 'nickname', type: 'text' },
        {
          name: 'posts',
          type: 'relationship',
          relationTo: 'posts',
          hasMany: true,
        },
      ],
      hooks: {
        afterChange: [
          ({ doc }) => {
            // your hook
          },
        ],
      },
    },
    session: {
      admin: { hidden: true },
    },
  },
})

For real projects, prefer extracting each collection into its own file just like you would for a regular Payload collection, typed with CollectionConfigExtend<'user'>:

// collections/User.ts
import type { CollectionConfigExtend } from '@b3nab/payload-better-auth'

export const User: CollectionConfigExtend<'user'> = {
  admin: { group: 'My App', useAsTitle: 'email' },
  fields: [
    { name: 'nickname', type: 'text' },
    // ...all the Payload fields you need
  ],
}

// payload-better-auth.config.ts
import { User } from '@/collections/User'

export const payloadBetterAuthConfig = {
  extendsCollections: { user: User },
  // ...
} as const

Notes:

• Extensions are deep-merged onto the generated config. Fields you add are appended to the Better Auth fields, not replacements.
• You can equivalently add custom fields through Better Auth's additionalFields on betterAuth.user (or betterAuth.session). Both paths feed into the same final Payload collection. Pick whichever fits the field's purpose:
  • Through betterAuth.user.additionalFields: the field is part of the Better Auth schema, so it's typed on session.user, accessible via auth.api.*, and persisted through Better Auth's own pipeline.
  • Through extendsCollections.user.fields: the field is Payload-native. Useful for Payload-only concerns like relationships to other Payload collections, custom admin UI components, or complex field types.
• Authentication-related fields are owned by Better Auth (e.g. password, emailVerified, TOTP secrets). Don't redeclare them in extendsCollections.