Payload

Use Payload when collections live in the same Next.js app and expose route, SEO, and media fields over the REST API.

Install

For CLI scans, @cms-lab/cli includes the bundled adapter. Add @cms-lab/core for defineConfig. Install @cms-lab/payload only when importing the adapter directly in project code or tests.

pnpm add -D @cms-lab/cli @cms-lab/core
pnpm add -D @cms-lab/payload

Config

import { defineConfig } from "@cms-lab/core";

export default defineConfig({
  site: { url: "http://localhost:3000" },
  framework: { type: "next", router: "app" },
  cms: {
    provider: "payload",
    url: "http://localhost:3000",
    apiPath: "/api",
    token: process.env.PAYLOAD_TOKEN,
    collections: [
      { type: "page", collection: "pages", uidField: "slug" },
      { type: "post", collection: "posts", uidField: "slug" },
    ],
  },
  routes: [
    { type: "page", pattern: "/:slug", getPath: (doc) => "/" + doc.uid },
    {
      type: "post",
      pattern: "/blog/:slug",
      getPath: (doc) => "/blog/" + doc.uid,
    },
  ],
});

UID and URL field mapping

Use uidField when the route key lives in a custom nested CMS field. Use urlField when the CMS stores the public permalink. Both read dotted paths from document.data.

cms: {
  provider: "payload",
  collections: [
    {
      type: "page",
      collection: "pages",
      uidField: "slug",
      urlField: "seo.canonical",
    },
    // Relation-heavy collections can be checked without route probing.
    { type: "pricing", collection: "pricing", uidField: "id", routable: false },
  ],
}

CI command

npx @cms-lab/cli doctor
npx @cms-lab/cli scan --ci --report --fail-on error

Provider caveats

• Reads the REST API at {url}{apiPath}/{collection}; apiPath defaults to /api.
• token is sent in the Authorization header (verbatim if it already has a scheme, otherwise as JWT), so both JWT and API-key auth work.
• Payload's _status draft flag maps onto the cms-lab published/draft status.
• Run cms-lab init --cms payload for a starter config.

Check the adapter maturity matrix before using this provider as a strict deploy gate.