Headless CMS skill for Codex

Done well means: content is typed end to end, the front end fetches only the fields it renders (references resolved in the query, not in loops), published pages update within seconds of a publish through webhook revalidation, editors can preview drafts without leaking preview tokens to the browser, and content model changes ship as reviewed migrations.

Choose (or confirm) the CMS

Need	Default	Why
Structured content, custom editorial UI, real-time collaboration, hosted	Sanity	Schema in code, GROQ projections, Studio is a React app you own
Enterprise governance, many locales, environments and roles	Contentful	Mature environments and aliases, migrations tooling
Self-hosted Node CMS with admin panel out of the box	Strapi 5	Open source, REST/GraphQL, your database
CMS inside the Next.js app itself, code-first, SQL database	Payload 3	Installs into /app, Local API with no HTTP hop

If the project already has one, keep it; this skill is about integrating well, not migrating. Read AGENTS.md, package.json and the CMS config (sanity.config.ts, payload.config.ts, src/api/**/content-types, or Contentful space settings) before changing anything.

Integration checklist

- [ ] Separate read-only delivery tokens (server only) from preview and write tokens
- [ ] Generate types from the content model; no hand-written `any` content shapes
- [ ] Queries select fields and resolve references in one request
- [ ] Fetch with cache tags; a CMS webhook calls a revalidation route on publish/unpublish
- [ ] Draft mode route enables preview with a secret, using the CMS's draft perspective/API
- [ ] Rich text rendered through the CMS's renderer, never raw HTML injection
- [ ] Images served through the CMS image pipeline with width, format and quality params
- [ ] Content model changes as migrations, tested on a copy (dataset, environment, DB)

Sanity

// lib/sanity.ts
import { createClient, defineQuery } from "next-sanity";

export const client = createClient({
  projectId: process.env.NEXT_PUBLIC_SANITY_PROJECT_ID!,
  dataset: process.env.NEXT_PUBLIC_SANITY_DATASET!,
  apiVersion: "2025-02-19",          // pin a date; bump deliberately
  useCdn: true,                      // false for drafts and read-after-write
});

export const POST_QUERY = defineQuery(`
  *[_type == "post" && slug.current == $slug][0]{
    _id, title, publishedAt,
    "author": author->{name, "avatar": image.asset->url},
    body,
    "cover": mainImage{asset->{url, metadata{dimensions, lqip}}, alt}
  }`);

export async function getPost(slug: string) {
  return client.fetch(POST_QUERY, { slug }, { next: { tags: [`post:${slug}`, "post"] } });
}

• Types: npx sanity schema extract && npx sanity typegen generate produces result types for each defineQuery.
• Always pass user input as GROQ params ($slug), never by string interpolation.
• Drafts: query with perspective: "drafts" and a viewer token on the server only; Visual Editing / Presentation tool builds on this.
• Rich text is Portable Text: render with @portabletext/react and explicit components for custom block types and marks.
• Webhooks: GROQ-powered webhooks with a filter (_type == "post") and projection ({slug}); verify with @sanity/webhook (isValidSignature) before revalidating.

Contentful

import { createClient } from "contentful";

const delivery = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  environment: process.env.CONTENTFUL_ENVIRONMENT ?? "master",
  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!,
});
const preview = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  environment: process.env.CONTENTFUL_ENVIRONMENT ?? "master",
  accessToken: process.env.CONTENTFUL_PREVIEW_TOKEN!,
  host: "preview.contentful.com",
});

const res = await delivery.getEntries({
  content_type: "blogPost",
  "fields.slug": slug,
  include: 2,                          // resolve linked entries two levels deep
  select: ["fields.title", "fields.slug", "fields.body", "fields.author"],
  limit: 1,
});

• Types: generate from the space (for example with cf-content-types-generator) and use the SDK’s generic entry types.
• Rich text: @contentful/rich-text-react-renderer with render options for embedded entries and assets.
• Model changes: write contentful-migration scripts and run them with the Contentful CLI against a new environment cloned from master; test, then point the master alias at it. Running a migration directly on production content needs explicit user confirmation.
• The Management API is tightly rate limited (a few requests per second); batch and back off. Delivery API responses are CDN cached and generous.

Strapi 5

const qs = new URLSearchParams({
  "filters[slug][$eq]": slug,
  "populate[cover][fields][0]": "url",
  "populate[author][fields][0]": "name",
  "fields[0]": "title",
  "fields[1]": "body",
  status: "published",                 // "draft" for preview
});
const res = await fetch(`${process.env.STRAPI_URL}/api/articles?${qs}`, {
  headers: { Authorization: `Bearer ${process.env.STRAPI_READ_TOKEN}` },
  next: { tags: [`article:${slug}`] },
});
const { data } = await res.json();     // v5: flat objects with documentId, no data.attributes

Strapi v4	Strapi v5
data[].attributes.title	data[].title (flattened)
numeric id as stable key	documentId (string) is the stable key across locales and drafts
publicationState=preview	status=draft
Entity Service API	Document Service API (strapi.documents("api::article.article"))

Use read-only API tokens for the front end, full-access tokens only in migration scripts. populate=* is one level only and over-fetches; populate explicitly.

Payload 3

// app/(site)/posts/[slug]/page.tsx
import { getPayload } from "payload";
import config from "@payload-config";
import { draftMode } from "next/headers";

export default async function Page({ params }: { params: Promise<{ slug: string }> }) {
  const { slug } = await params;
  const { isEnabled: draft } = await draftMode();
  const payload = await getPayload({ config });
  const { docs } = await payload.find({
    collection: "posts",
    where: { slug: { equals: slug } },
    depth: 1,
    draft,
    limit: 1,
    overrideAccess: false,             // enforce collection access rules
  });
  ...
}

• The Local API bypasses access control by default (overrideAccess: true); pass overrideAccess: false (and user) whenever results reach end users.
• Types: payload generate:types. Postgres schema changes: payload migrate:create, review the SQL, run payload migrate in deploy.
• Revalidate in collection afterChange hooks with revalidateTag instead of webhooks.

Revalidation and preview (Next.js)

// app/api/revalidate/route.ts
import { revalidateTag } from "next/cache";

export async function POST(req: Request) {
  if (req.headers.get("x-revalidate-secret") !== process.env.REVALIDATE_SECRET) {
    return new Response("Unauthorized", { status: 401 });
  }
  const { type, slug } = await req.json();
  revalidateTag(type);
  if (slug) revalidateTag(`${type}:${slug}`);
  return Response.json({ revalidated: true });
}

Prefer the CMS’s signature verification (Sanity, Contentful and Strapi all support secret headers or signatures) over a shared header when available. Check the revalidateTag signature for the project’s Next.js version; newer versions accept a cache-life profile argument.

Draft mode route: verify a secret, call (await draftMode()).enable(), redirect to the requested path (validate it is a relative path to avoid open redirects). In draft mode, use the preview client or draft perspective and disable caching for those requests.

Gotchas

• Stale content after publish: CDN client (useCdn: true) read right after a write, or tags in fetch do not match the tags revalidated.
• Reference fetching in loops (N+1): resolve with GROQ ->, Contentful include, Strapi populate, Payload depth.
• Locales: decide fallback behaviour explicitly; missing translations otherwise render empty.
• Preview or write tokens in NEXT_PUBLIC_* variables leak to every visitor.
• Deleting content types or fields drops data for every entry; confirm and migrate first.
• Slugs are not unique unless the model enforces it; validate in the schema.

Verification

• Type check passes with generated types; no any in content access.
• Publish a change in the CMS and confirm the page updates within the expected seconds; check the revalidation route’s logs for the matching tag.
• Open a draft through the preview link, then confirm the public page does not show it.
• Run migrations against a copy (dataset, environment, database branch) before production.