Claude Code e Contentful CMS: guia prático de integração

Comece pelo limite da integração

Contentful é um CMS headless: o time editorial gerencia conteúdo estruturado no Contentful, enquanto o site renderiza esse conteúdo por APIs. Isso funciona bem para blogs, páginas de produto, documentação, notícias e sites multilíngues. Claude Code pode acelerar a implementação, mas a qualidade depende do contrato que você entrega a ele.

Pedir apenas “conecte Contentful” costuma gerar uma demonstração que busca uma entrada publicada. Essa demo parece correta até alguém tentar pré-visualizar um rascunho, abrir a versão pt-BR, publicar uma imagem ou esperar que uma página Next.js seja revalidada. A integração real envolve Content Delivery API, Content Preview API, Content Management API, variáveis de ambiente, locales, tipos, SSG, ISR e webhooks.

Para a arquitetura geral de um blog CMS, veja Claude Code blog CMS. Se o conteúdo também precisa alimentar APIs de produto, conecte com Claude Code API development. Para transformar conteúdo em inscrição, compra ou consultoria, content funnel audit complementa a estratégia.

Separe Delivery, Preview e Management

As APIs do Contentful têm responsabilidades diferentes. Misturar token e host torna o sistema inseguro e difícil de revisar.

API	Uso	Token	Onde usar
Content Delivery API	Ler conteúdo publicado	Delivery token	SSG, ISR, Server Components, builds do Astro
Content Preview API	Ler rascunhos e alterações não publicadas	Preview token	rotas de preview no servidor
Content Management API	Criar modelos, editar entries, publicar	Management token ou PAT	scripts locais e CI confiável
Images API	Redimensionar e formatar assets	contexto delivery/preview	helpers de imagem, thumbnails, OGP

Na documentação oficial do SDK JavaScript, o preview usa preview access token e host: "preview.contentful.com". Personal Access Tokens da Management API estão ligados a permissões de usuário e devem ser protegidos como credenciais. Consulte Contentful JavaScript SDK, Personal Access Tokens, environment permissions e o guia Contentful do Astro.

Prompt claro para Claude Code

Um prompt útil define APIs, arquivos, locale, preview e validação. Isso reduz decisões invisíveis.

Implemente uma integração de blog com Contentful neste repositório.
- Conteúdo publicado usa apenas Content Delivery API.
- Preview mode usa apenas Content Preview API.
- Content Management API token fica restrito a scripts/setup-contentful-model.ts.
- O locale padrão é pt-BR; en-US deve ser aceito como parâmetro.
- Next.js usa Draft Mode e revalidatePath para webhooks.
- Astro lê entries no getStaticPaths durante o build.
- Preview token e Management token não podem ir para o navegador.
- No final, liste arquivos modificados e comandos de verificação.

Com esse contrato, o diff fica auditável. Se Claude Code colocar CONTENTFUL_PREVIEW_TOKEN em um componente cliente, o erro aparece. Se mantiver cdn.contentful.com durante preview, o código contradiz a regra. Se esquecer locale, a revisão encontra antes do deploy.

Modele por caso de uso

Contentful funciona melhor quando o conteúdo é estruturado. Um campo Rich Text gigante é rápido no início, mas atrapalha tradução, CTA, analytics e busca.

Caso de uso	Campos principais	Cache	Objetivo
Blog técnico	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + webhook de publicação	PDF grátis, artigos relacionados, treinamento
Landing de produto	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	ISR curto ou revalidação manual	compra, demo, consultoria
Documentação	category, version, body, relatedDocs, updatedAt	SSG e sincronização de busca	suporte pago, templates
Notícias localizadas	title/body por locale, region, canonicalSlug	builds por locale	CTAs regionais e leads

Em um teste, o erro foi usar blogPost para artigos e landings. O artigo funcionava, mas a landing precisava de preço, FAQ, CTA e rótulos de experimento. O time editorial começou a colocar botões dentro do Rich Text, o que dificultou análise de cliques e consistência visual. Claude Code pode refatorar depois, mas é melhor começar com um modelo certo.

Variáveis de ambiente e locales

Crie um .env.example antes dos componentes. Ele documenta a função de cada segredo.

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=pt-BR
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 e Management token nunca devem receber o prefixo NEXT_PUBLIC_. Em Next.js, esse prefixo pode expor o valor no navegador. O token de preview lê conteúdo não publicado, e o token de management pode alterar o espaço. Eles devem ficar no servidor, em scripts locais ou em uma CI controlada.

Também revise o environment. Muitos exemplos usam master, mas times reais usam production, staging ou aliases. Um token pode funcionar em master e falhar com 403 em outro environment. Locales também variam: pt-BR, pt-PT ou nomes internos. Toda função de leitura deve aceitar locale.

Cliente tipado para Contentful

Centralize a escolha de token e host. As páginas só informam se estão em preview e qual locale querem ler.

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

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

Quando o modelo crescer, gere tipos a partir do Contentful e faça a CI falhar em caso de divergência. O ponto principal continua igual: content type ID, field ID, locale e preview não devem ficar espalhados pelos componentes.

Next.js e Astro em papéis diferentes

Next.js é uma boa escolha quando preview e revalidação sob demanda são importantes. Páginas públicas podem ser estáticas, rascunhos podem usar Draft Mode com Preview API, e webhooks do Contentful podem chamar uma rota que executa revalidatePath. Confira a versão atual de draftMode e revalidatePath, porque exemplos antigos podem não refletir a API atual.

Astro é excelente para saída estática previsível. Use getStaticPaths para buscar entries e renderize HTML no build. O custo é operacional: uma edição no Contentful não atualiza automaticamente o HTML publicado. Você precisa de um webhook que dispare rebuild na plataforma, ou separar páginas que mudam muito para Next.js com ISR. Blog e documentação combinam com Astro SSG; landings editadas toda semana combinam mais com ISR.

Erros para revisar antes do deploy

Erro	Sintoma	Correção
Preview token no host de Delivery	401 ou rascunho invisível	usar preview.contentful.com
Delivery token em preview	página de rascunho retorna null	usar Content Preview API
Management token exposto	vazamento grave de segredo	limitar a scripts/CI
Locale omitido	idioma errado ou campos vazios	passar locale em cada query
Asset não publicado	texto aparece, imagem falta	publicar entry e asset
Webhook em cada save	cache de produção invalida demais	usar publish/unpublish
Field ID renomeado	tipos e render quebram	manter API identifiers

Não finalize a validação apenas em next dev. Teste build, preview, webhook e locale em um ambiente parecido com produção. Peça a Claude Code uma tabela final com token, host, locale e path por rota crítica. Essa tabela costuma revelar erros escondidos.

Conecte o CMS à monetização

Uma integração de CMS deve apoiar o caminho de receita. Em vez de esconder todos os CTAs no Rich Text, crie campos como ctaKind, ctaLabel, ctaUrl e relatedPosts. Um tutorial técnico pode levar ao cheatsheet gratuito, um artigo sobre adoção em equipe pode apontar para training and consultation, e conteúdos de template podem seguir para products.

Essa estrutura mantém analytics limpo: cta_click tem identificador estável, editores mudam texto sem quebrar componentes, e Claude Code consegue revisar o contrato entre Contentful e UI. Ao testar esse fluxo, a maior melhoria veio de separar Delivery, Preview e Management no prompt inicial. Os diffs ficaram menores, erros de locale apareceram na revisão, e problemas de preview deixaram de chegar ao deploy.