Claude Code und Contentful CMS: praktische Integrationsanleitung

Erst die Integrationsgrenze klären

Contentful ist ein Headless CMS. Redaktionsteams pflegen strukturierte Inhalte in Contentful, während die Website diese Inhalte über APIs rendert. Das passt für Blogs, Produktseiten, Dokumentation und mehrsprachige Websites. Claude Code kann die Integration beschleunigen, aber nur, wenn die Grenze zwischen Modell, API, Preview, Cache und Deployment klar ist.

Die schwache Anweisung “verbinde Contentful” führt oft zu einer Demo, die genau einen veröffentlichten Eintrag anzeigt. Später bricht sie bei einem Entwurf, bei de-DE, bei nicht veröffentlichten Bildern oder bei Next.js-Caches. Eine belastbare Integration unterscheidet Content Delivery API, Content Preview API, Content Management API, Umgebungsvariablen, Locales, Typen, SSG, ISR und Webhooks.

Für das größere Blog-CMS-Muster passt Claude Code blog CMS. Wenn CMS-Inhalte auch Produkt-APIs speisen sollen, ist Claude Code API development relevant. Für die Verbindung von Content und Umsatz ist content funnel audit der nächste sinnvolle Schritt.

Delivery, Preview und Management trennen

Contentful hat mehrere APIs. Sie sollten nicht denselben Token, denselben Host oder dieselbe Code-Schicht teilen.

API	Zweck	Token	Einsatzort
Content Delivery API	veröffentlichte Einträge und Assets lesen	Delivery token	SSG, ISR, Server Components, Astro Builds
Content Preview API	Entwürfe und unveröffentlichte Änderungen lesen	Preview token	serverseitige Preview-Routen
Content Management API	Modelle, Entries und Publishing verwalten	Management token oder PAT	lokale Scripts und vertrauenswürdige CI
Images API	Bilder transformieren	Delivery/Preview-Kontext	Image Helper, Thumbnails, OGP

Die offizielle JavaScript-SDK-Dokumentation beschreibt Preview mit preview access token und host: "preview.contentful.com". Personal Access Tokens für die Management API sind an Benutzerrechte gebunden und gehören nicht in den Browser. Gute Referenzen sind Contentful JavaScript SDK, Personal Access Tokens, environment permissions und der Astro Contentful Guide.

Ein konkreter Prompt für Claude Code

Der Prompt sollte nicht nur “baue das” sagen, sondern Regeln und Prüfungen enthalten.

Implementiere eine Contentful-Blog-Integration in diesem Repository.
- Veröffentlichte Inhalte nutzen nur die Content Delivery API.
- Preview Mode nutzt nur die Content Preview API.
- Content Management API token darf nur in scripts/setup-contentful-model.ts vorkommen.
- Standard-Locale ist de-DE; en-US soll als Parameter möglich sein.
- Next.js nutzt Draft Mode und revalidatePath für Webhooks.
- Astro liest Entries im Build über getStaticPaths.
- Preview token und Management token dürfen nicht im Browser landen.
- Am Ende bitte geänderte Dateien und ausgeführte Prüfungen auflisten.

Damit wird der Diff überprüfbar. Wenn Claude Code CONTENTFUL_PREVIEW_TOKEN in Client-Code schreibt, ist der Fehler offensichtlich. Wenn Preview weiter cdn.contentful.com nutzt, widerspricht es der Vorgabe. Wenn Locale-Parameter fehlen, fällt das vor dem Deployment auf.

Content Model nach Anwendungsfall planen

Contentful ist stark, wenn Inhalte strukturiert sind. Ein einzelnes Rich-Text-Feld reicht für eine Demo, wird aber bei CTA, Lokalisierung, Analytics und Suche schnell teuer.

Anwendungsfall	Felder	Cache-Strategie	Ziel
Technischer Blog	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + Publish-Webhook	Freebie, verwandte Artikel, Training
Produkt-Landingpage	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	kurzes ISR oder manuelle Revalidierung	Kauf, Demo, Beratung
Dokumentation	category, version, body, relatedDocs, updatedAt	SSG und Suchindex-Sync	Support, Templates
Lokalisierte News	title/body pro Locale, region, canonicalSlug	Builds pro Locale	regionale CTAs und Leads

In einem Testprojekt war der Fehler, Blogartikel und Landingpages in denselben Typ blogPost zu legen. Der Artikel funktionierte, aber die Landingpage brauchte Preise, FAQ, CTA-Varianten und Experiment-Labels. Redaktionelle Buttons im Rich Text machten spätere Klickmessung schwierig. Claude Code kann so etwas refaktorieren, aber ein getrenntes Modell ist die bessere Ausgangslage.

Umgebungsvariablen und Locales

Ein .env.example verhindert Token-Verwechslungen und hilft Claude Code, die Rollen zu verstehen.

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=de-DE
CONTENTFUL_DELIVERY_TOKEN=delivery_token_for_published_content
CONTENTFUL_PREVIEW_TOKEN=preview_token_for_drafts
CONTENTFUL_MANAGEMENT_TOKEN=management_token_for_scripts
CONTENTFUL_PREVIEW_SECRET=random_secret_for_draft_mode
CONTENTFUL_REVALIDATE_SECRET=random_secret_for_webhooks
NEXT_PUBLIC_SITE_URL=http://localhost:3000

Preview token und Management token dürfen nicht mit NEXT_PUBLIC_ beginnen. In Next.js kann dieser Präfix Werte an den Browser ausliefern. Der Preview token kann unveröffentlichte Inhalte lesen, der Management token kann den Space ändern. Beide gehören in Server-Routen, lokale Scripts oder eine kontrollierte CI.

Auch Environment und Locale sind Fehlerquellen. Viele Beispiele verwenden master, aber Teams arbeiten oft mit production, staging oder Environment Aliases. Ein Token kann auf master funktionieren und auf production 403 liefern. Bei Sprachen gilt dasselbe: de-DE, de-AT oder eigene Locales sind möglich. Jede Fetch-Funktion sollte eine Locale akzeptieren.

Typisierter Contentful-Client

Host und Token-Auswahl gehören an eine Stelle. Seiten geben nur an, ob Preview aktiv ist und welche Locale gelesen wird.

// src/lib/contentful.ts
import { createClient, type EntryFieldTypes, type EntrySkeletonType } from "contentful";

type BlogPostFields = {
  title: EntryFieldTypes.Symbol;
  slug: EntryFieldTypes.Symbol;
  excerpt: EntryFieldTypes.Text;
  body: EntryFieldTypes.RichText;
  heroImage: EntryFieldTypes.AssetLink;
  tags: EntryFieldTypes.Array<EntryFieldTypes.Symbol>;
  publishedAt: EntryFieldTypes.Date;
};

export type BlogPostSkeleton = EntrySkeletonType<BlogPostFields, "blogPost">;

function required(name: string): string {
  const value = process.env[name];
  if (!value) throw new Error(`${name} is required`);
  return value;
}

export function getContentfulClient(options: { preview?: boolean } = {}) {
  const preview = options.preview ?? false;

  return createClient({
    space: required("CONTENTFUL_SPACE_ID"),
    environment: process.env.CONTENTFUL_ENVIRONMENT ?? "master",
    accessToken: preview
      ? required("CONTENTFUL_PREVIEW_TOKEN")
      : required("CONTENTFUL_DELIVERY_TOKEN"),
    host: preview ? "preview.contentful.com" : "cdn.contentful.com",
  });
}

export async function getBlogPostBySlug(
  slug: string,
  options: { locale?: string; preview?: boolean } = {},
) {
  const locale = options.locale ?? process.env.CONTENTFUL_DEFAULT_LOCALE ?? "de-DE";
  const response = await getContentfulClient(options).getEntries<BlogPostSkeleton>({
    content_type: "blogPost",
    "fields.slug": slug,
    limit: 1,
    include: 2,
    locale,
  });

  return response.items[0] ?? null;
}

Bei größeren Modellen lohnt sich Type-Generierung aus Contentful und ein CI-Check gegen Drift. Der Grundsatz bleibt gleich: Content Type IDs, Field IDs, Locale und Preview-Zustand gehören nicht verstreut in Komponenten.

Next.js oder Astro gezielt einsetzen

Next.js ist stark, wenn Preview und On-Demand-Revalidierung wichtig sind. Öffentliche Seiten können statisch sein, Entwürfe laufen über Draft Mode und Preview API, und Contentful-Webhooks können eine Route mit revalidatePath auslösen. Prüfen Sie die aktuelle Dokumentation zu draftMode und revalidatePath, weil alte Beispiele leicht falsche Annahmen enthalten.

Astro ist ideal für stabile statische Seiten. Entries werden in getStaticPaths gelesen und beim Build zu HTML gerendert. Eine Änderung in Contentful aktualisiert aber nicht automatisch das bereits deployte HTML. Dafür braucht man einen Rebuild-Webhook der Plattform oder eine Trennung: Blog und Dokumentation in Astro SSG, schnell wechselnde Landingpages in Next.js ISR.

Fehler vor dem Go-live prüfen

Fehler	Symptom	Lösung
Preview token am Delivery Host	401 oder kein Entwurf	preview.contentful.com verwenden
Delivery token für Entwürfe	Preview-Seite ist null	Content Preview API nutzen
Management token exponiert	kritisches Secret-Leak	nur Scripts/CI
Locale fehlt	falsche Sprache oder leere Felder	Locale bei jeder Query setzen
Asset nicht veröffentlicht	Text da, Bild fehlt	Entry und Asset publishen
Webhook bei jedem Save	Produktionscache leert sich ständig	nur publish/unpublish
Field ID geändert	Typen und Rendering brechen	API identifiers beibehalten

Die letzte Prüfung sollte nicht nur im Dev-Server laufen. Next.js-Revalidierung muss nahe am Produktionsbuild getestet werden. Bei Astro sind Build-Ergebnis und Rebuild-Webhook entscheidend. Lassen Sie Claude Code zum Abschluss pro Route Token, Host, Locale und Path tabellarisch ausgeben.

CMS-Struktur mit Monetarisierung verbinden

Eine CMS-Integration sollte auch den nächsten Schritt des Lesers unterstützen. Strukturieren Sie ctaKind, ctaLabel, ctaUrl und relatedPosts, statt alle CTAs in Rich Text zu verstecken. Ein technischer Artikel kann zum kostenlosen Cheat Sheet führen, Team-Einführung zu training and consultation, Template-Inhalte zu products.

So bleibt die Analyse sauber: cta_click hat eine stabile ID, Redakteure können Texte ändern, und Komponenten bleiben konsistent. Beim Testen dieser Architektur war der größte Gewinn die frühe Trennung von Delivery, Preview und Management. Claude Code erzeugte kleinere Diffs, Locale-Fehler wurden in der Review sichtbar, und Preview-Probleme ließen sich beheben, bevor sie in Produktion auffielen.