Contentful

Use Contentful when content types expose slug-like fields and a delivery token can read entries.

Install

For CLI scans, @cms-lab/cli includes the bundled adapter. Add @cms-lab/core for defineConfig. Install @cms-lab/contentful 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/contentful

Config

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

export default defineConfig({
  site: { url: "http://localhost:3000" },
  framework: { type: "next", router: "app" },
  cms: {
    provider: "contentful",
    spaceId: "my-space",
    environment: "master",
    accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN,
    contentTypes: [
      { type: "page", contentType: "page", uidField: "slug" },
      { type: "article", contentType: "article", uidField: "routing.slug" },
    ],
  },
  routes: [
    { type: "page", pattern: "/:slug", getPath: (doc) => "/" + doc.uid },
    { type: "article", 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: "contentful",
  contentTypes: [
    {
      type: "page",
      contentType: "page",
      uidField: "routing.slug",
      urlField: "routing.url",
    },
  ],
}

CI command

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

Provider caveats

• The adapter uses the Content Delivery API and paginates entries.
• Top-level localized field objects are flattened to a default locale when possible.
• Reference expansion and preview API scans are not built in yet.

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