payload-authjs

To support different user types (e.g., customers and admins) in a single application, you can register multiple instances of the payload-authjs plugin within your Payload CMS configuration. Each plugin instance is tied to a specific collection and maintains its own Auth.js configuration, handlers, and authentication workflows.

In a typical setup:

• Each collection (e.g., customers, admins) has a dedicated Auth.js configuration file.
• Each collection has its own set of Auth.js handlers.
• The payload.config.ts file includes a separate payload-authjs plugin entry for every authentication collection you wish to support.

// src/payload.config.ts
// Example of registering multiple plugins
export default buildConfig({
  // ... other config
  plugins: [
    payloadAuthjs({ 
      collection: customers, 
      authConfig: customersAuthConfig 
    }),
    payloadAuthjs({ 
      collection: admins, 
      authConfig: adminsAuthConfig 
    }),
  ],
});

Before adding the plugin to Payload, you must configure Auth.js. This involves three main steps:

1. Create Auth.js configuration

Define your providers in an auth.config.ts file.

2. Create the Auth.js instance

Use getAuthjsInstance from payload-authjs. Note that you must initialize the Payload instance first.

3. Add the route handler

Expose the Auth.js handlers in your Next.js app router at /app/api/auth/[...nextauth]/route.ts.

// 1. auth.config.ts
import type { NextAuthConfig } from "next-auth";
import github from "next-auth/providers/github";

export const authConfig: NextAuthConfig = {
  providers: [github],
};

// 2. auth.ts
import payloadConfig from "@payload-config";
import { getPayload } from "payload";
import { getAuthjsInstance } from "payload-authjs";

const payload = await getPayload({ config: payloadConfig });
export const { handlers, signIn, signOut, auth } = getAuthjsInstance(payload);

// 3. app/api/auth/[...nextauth]/route.ts
import { handlers } from "@/auth";
export const { GET, POST } = handlers;

If you are using the Auth.js jwt session strategy, you can add data to the user object without storing it in the database by using Payload virtual fields.

To make this work, you must:

1. Define the field in your collection with virtual: true.
2. Extend the Auth.js jwt callback to include the data in the token.
3. Extend the Auth.js session callback to forward the data from the token to the session.

The plugin will then automatically extract these virtual fields from the Auth.js session and attach them to the Payload user object.

// 1. Define virtual field in Payload
const Users: CollectionConfig = {
  slug: "users",
  fields: [
    {
      name: "roles",
      type: "json",
      virtual: true,
      admin: { hidden: true },
    },
  ],
};

// 2. Extend Auth.js JWT and Session callbacks
const authConfig: NextAuthConfig = {
  callbacks: {
    jwt: ({ token, trigger }) => {
      if (trigger === "signIn" || trigger === "signUp") {
        token.roles = ["example-role"];
      }
      return token;
    },
    session: ({ session, token }) => {
      if (token) {
        session.user.roles = token.roles;
      }
      return session;
    },
  },
};

To store additional user data permanently in the database, add a new field to your Payload users collection and extend your Auth.js provider's profile method to map the incoming provider data to that field.

Note: Auth.js does not automatically update the user record after the initial sign-in. To sync data on every sign-in, use the signIn event instead.

// 1. Add field to Payload collection
const Users: CollectionConfig = {
  slug: "users",
  fields: [
    {
      name: "locale",
      type: "text",
    },
  ],
};

// 2. Extend Auth.js provider profile mapping
const authConfig: NextAuthConfig = {
  providers: [
    keycloak({
      profile(profile) {
        return {
          id: profile.sub,
          name: profile.name,
          email: profile.email,
          image: profile.picture,
          locale: profile.locale, // <-- Map custom field
        };
      },
    }),
  ],
};