Claude Code y Contentful CMS: guía práctica de integración

Define el límite antes de escribir código

Contentful es un CMS headless: el equipo editorial administra contenido estructurado en Contentful y el sitio lo consume mediante APIs. Esto permite publicar artículos, páginas de producto, documentación, imágenes, autores y CTAs sin acoplarlos al código de la interfaz. Claude Code ayuda mucho en este flujo, pero solo si le das un contrato claro.

El error típico es pedir “conecta Contentful” y aceptar el primer código que muestra una entrada publicada. Ese demo puede funcionar con una página en inglés, pero fallar cuando el editor quiere previsualizar un borrador, cuando la entrada está en es-ES, cuando la imagen no está publicada o cuando Next.js conserva una versión antigua por caché. La integración real incluye Content Delivery API, Content Preview API, Content Management API, variables de entorno, locales, tipos, preview, SSG e ISR.

Para el patrón completo de CMS de blog puedes leer Claude Code blog CMS. Si el contenido debe alimentar APIs de producto, conecta este tema con Claude Code API development. Para convertir contenido en leads, compras o consultas, revisa también content funnel audit.

Separa Delivery, Preview y Management

Contentful tiene varias APIs y cada una tiene un propósito distinto. No conviene usar el mismo token ni el mismo host para todo.

API	Uso	Token	Lugar recomendado
Content Delivery API	Contenido publicado	Delivery token	SSG, ISR, Server Components, builds de Astro
Content Preview API	Borradores y cambios no publicados	Preview token	rutas de preview en servidor
Content Management API	Crear modelos, editar entries, publicar	Management token o PAT	scripts locales y CI confiable
Images API	Redimensionar y transformar imágenes	contexto delivery/preview	helpers de imagen, miniaturas, OGP

La documentación oficial del SDK de JavaScript indica que el preview se hace con el preview access token y host: "preview.contentful.com". Los Personal Access Tokens de Management API están ligados a permisos de usuario y deben tratarse como credenciales sensibles. Mantén cerca estas referencias: Contentful JavaScript SDK, Personal Access Tokens, environment permissions y guía de Contentful para Astro.

Prompt recomendado para Claude Code

Un buen prompt no solo pide código. También fija límites, archivos y comandos de verificación.

Implementa una integración de blog con Contentful en este repositorio.
- Usa Content Delivery API solo para contenido publicado.
- Usa Content Preview API solo cuando preview mode esté activo.
- Usa Content Management API únicamente en scripts/setup-contentful-model.ts.
- El locale por defecto es es-ES; las funciones deben aceptar en-US.
- Next.js debe usar Draft Mode y revalidatePath para webhooks.
- Astro debe leer entries en getStaticPaths durante el build.
- No expongas Preview token ni Management token al navegador.
- Al final, lista los archivos modificados y los comandos ejecutados.

Con esta instrucción, el diff es revisable. Si Claude Code coloca CONTENTFUL_PREVIEW_TOKEN en un componente cliente, el error se detecta rápido. Si usa cdn.contentful.com para borradores, el contrato lo contradice. Si olvida el locale, la revisión lo captura antes de producción.

Modela por caso de uso

Contentful brilla cuando el contenido está estructurado. Meter todo en un único campo Rich Text parece rápido, pero complica CTAs, analítica, traducción y pruebas A/B.

Caso de uso	Campos habituales	Caché	Resultado buscado
Blog técnico	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + webhook de publicación	PDF gratuito, artículos relacionados, formación
Landing de producto	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	ISR corto o revalidación manual	compra, demo, consulta
Documentación	category, version, body, relatedDocs, updatedAt	SSG y sincronización con buscador	soporte de pago, plantillas
Noticias localizadas	title/body por locale, region, canonicalSlug	builds por locale	CTA regionales y ventas locales

En una prueba, el fallo fue usar blogPost tanto para artículos como para landings. La primera página funcionó, pero la landing necesitaba precio, FAQ, CTA y etiquetas de experimento. El equipo editorial empezó a escribir botones dentro del cuerpo y después fue difícil medir clics o cambiar el diseño. Claude Code puede refactorizarlo, pero es más barato diseñar bien el modelo desde el principio.

Variables de entorno y locales

Antes de escribir componentes, crea una plantilla de entorno. Así Claude Code ve qué secreto pertenece a cada API.

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=es-ES
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

Nunca pongas Preview token ni Management token detrás de NEXT_PUBLIC_. En Next.js ese prefijo puede exponer el valor al navegador. El token de preview permite leer contenido no publicado y el token de management puede modificar el espacio, así que deben vivir solo en servidor, scripts locales o CI confiable.

También revisa el environment. Muchos ejemplos usan master, pero los equipos suelen tener production, staging o environment aliases. Un token con permiso en master puede devolver 403 en otro environment. Los locales tampoco son universales: puede ser es-ES, es-MX o una convención propia. Toda función de lectura debe aceptar locale.

Cliente tipado para Contentful

Concentra la selección de host y token en una fábrica de cliente. El resto del código solo decide si está en preview y qué locale quiere.

// 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 ?? "es-ES";
  const response = await getContentfulClient(options).getEntries<BlogPostSkeleton>({
    content_type: "blogPost",
    "fields.slug": slug,
    limit: 1,
    include: 2,
    locale,
  });

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

Cuando el modelo crezca, genera tipos desde Contentful y revisa los cambios en CI. Lo importante es que los IDs de content type, los field IDs, el locale y el estado de preview no queden repartidos por componentes sin control.

Next.js y Astro no resuelven el mismo problema

Next.js es cómodo cuando necesitas preview y revalidación bajo demanda. Las páginas públicas pueden ser estáticas, el borrador puede usar Draft Mode con Preview API, y el webhook de Contentful puede llamar a una ruta que ejecute revalidatePath. Consulta la versión actual de draftMode y revalidatePath, porque copiar ejemplos antiguos puede romperse si la API cambió.

Astro encaja muy bien con páginas estables. En getStaticPaths lees las entries y generas HTML durante el build. Es rápido y simple, pero una edición en Contentful no cambia automáticamente el HTML ya desplegado. Necesitas un webhook que dispare un rebuild de la plataforma, o separar páginas con cambios frecuentes en Next.js. Para blogs y documentación, Astro SSG suele ser suficiente; para landings que se editan a diario, ISR es más flexible.

Errores frecuentes antes de publicar

Error	Síntoma	Corrección
Preview token con Delivery host	401 o borrador invisible	usar preview.contentful.com en preview
Delivery token para borradores	la página devuelve null	usar Content Preview API
Management token expuesto	fuga grave de secretos	limitarlo a scripts/CI
Locale omitido	idioma equivocado o campos vacíos	pasar locale en cada consulta
Asset sin publicar	el texto aparece pero falta la imagen	publicar entry y asset
Webhook en cada guardado	caché de producción se vacía sin necesidad	escuchar publish/unpublish
Field ID renombrado	se rompen tipos y renderizado	mantener API identifiers

La verificación final debe ir más allá de next dev. Comprueba el build de producción, la ruta de preview, el webhook de revalidación y los locales principales. Pide a Claude Code que entregue una tabla con token, host, locale y path por cada ruta crítica.

Conecta el CMS con monetización

La integración también debe ayudar a convertir lectores en acciones. En lugar de escribir todos los CTAs dentro de Rich Text, crea campos como ctaKind, ctaLabel, ctaUrl y relatedPosts. Un tutorial técnico puede enviar a un cheatsheet gratuito, un artículo de adopción en equipo puede apuntar a training and consultation, y un contenido de plantillas puede llevar a products.

Esta estructura permite medir cta_click con un identificador estable y cambiar textos sin tocar componentes. Al probar este flujo, la mejora más clara vino de separar Delivery, Preview y Management desde el prompt inicial. Claude Code produjo diffs más pequeños, los errores de locale se detectaron antes y el preview dejó de depender de suposiciones ocultas.