Integrasi Contentful CMS dengan Claude Code

Mulai dari batas integrasi

Contentful adalah headless CMS. Editor mengelola artikel, gambar, penulis, FAQ, CTA, dan konten terstruktur lain di Contentful, lalu frontend mengambilnya lewat API untuk dirender di Next.js, Astro, atau aplikasi lain. Claude Code bisa mempercepat pekerjaan ini, tetapi hasilnya hanya stabil kalau batas integrasinya jelas.

Permintaan “hubungkan Contentful” terlalu umum. Biasanya kode pertama hanya berhasil mengambil satu entry yang sudah publish. Masalah baru terlihat saat editor ingin preview draft, membuka versi id-ID, publish gambar, atau mengharapkan halaman Next.js direvalidate setelah webhook Contentful berjalan. Integrasi yang siap produksi harus memisahkan Content Delivery API, Content Preview API, Content Management API, environment variable, locale, type, SSG, ISR, dan webhook.

Untuk pola CMS blog yang lebih luas, baca Claude Code blog CMS. Jika konten CMS juga dipakai oleh API produk, lanjutkan ke Claude Code API development. Untuk menghubungkan konten dengan leads, pembelian, atau konsultasi, content funnel audit relevan.

Pisahkan Delivery, Preview, dan Management

Contentful menyediakan beberapa API dengan fungsi berbeda. Jangan mencampur token dan host untuk semua kebutuhan.

API	Fungsi	Token	Lokasi penggunaan
Content Delivery API	Membaca konten yang sudah publish	Delivery token	SSG, ISR, Server Component, build Astro
Content Preview API	Membaca draft dan perubahan belum publish	Preview token	route preview di server
Content Management API	Membuat model, mengubah entry, publish	Management token atau PAT	script lokal dan CI tepercaya
Images API	Resize dan format gambar	konteks delivery/preview	helper image, thumbnail, OGP

Dokumentasi resmi JavaScript SDK menjelaskan bahwa preview memakai preview access token dan host: "preview.contentful.com". Personal Access Token untuk Management API terikat ke izin pengguna, jadi perlakukan seperti credential sensitif. Referensi yang perlu dibuka: Contentful JavaScript SDK, Personal Access Tokens, environment permissions, dan panduan Contentful untuk Astro.

Prompt yang lebih aman untuk Claude Code

Prompt harus menjelaskan API, file, locale, preview, dan verifikasi. Dengan begitu, hasil Claude Code lebih mudah direview.

Implementasikan integrasi blog Contentful di repositori ini.
- Konten publish hanya memakai Content Delivery API.
- Preview mode hanya memakai Content Preview API.
- Content Management API token hanya boleh ada di scripts/setup-contentful-model.ts.
- Locale default adalah id-ID; fungsi tetap menerima en-US.
- Next.js memakai Draft Mode dan revalidatePath untuk webhook.
- Astro mengambil entries di getStaticPaths saat build.
- Preview token dan Management token tidak boleh terekspos ke browser.
- Di akhir, tulis file yang berubah dan command verifikasi.

Prompt seperti ini membuat kesalahan terlihat. Jika Claude Code menaruh CONTENTFUL_PREVIEW_TOKEN di client component, review langsung menolaknya. Jika draft tetap diambil dari cdn.contentful.com, berarti host preview belum benar. Jika locale tidak diteruskan, bug bahasa bisa ditangkap sebelum deploy.

Desain model berdasarkan use case

Contentful paling kuat saat konten terstruktur. Satu field Rich Text memang cepat, tetapi sulit untuk CTA, analytics, lokalisasi, dan pencarian.

Use case	Field utama	Cache	Tujuan
Blog teknis	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + webhook publish	PDF gratis, artikel terkait, training lead
Landing produk	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	ISR pendek atau manual revalidate	pembelian, demo, konsultasi
Dokumentasi	category, version, body, relatedDocs, updatedAt	SSG dan sinkronisasi search	support berbayar, template
Berita lokal	title/body per locale, region, canonicalSlug	build per locale	CTA regional dan sales lead

Dalam sebuah percobaan, kesalahan utamanya adalah memakai blogPost untuk artikel dan landing page sekaligus. Artikel tampil baik, tetapi landing page membutuhkan harga, FAQ, CTA, dan label eksperimen. Editor akhirnya menulis tombol langsung di Rich Text, sehingga tracking klik dan konsistensi UI menjadi sulit. Claude Code bisa membantu refactor, tetapi model yang benar sejak awal jauh lebih murah.

Environment variable dan locale

Buat .env.example sebelum menulis komponen. File ini menjadi kontrak kecil untuk token dan lingkungan.

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=id-ID
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

Jangan beri prefix NEXT_PUBLIC_ pada Preview token atau Management token. Di Next.js, prefix itu bisa membuat nilai masuk ke bundle browser. Preview token dapat membaca konten yang belum publish, sedangkan Management token dapat mengubah space. Keduanya hanya boleh ada di server, script lokal, atau CI yang tepercaya.

Environment juga perlu dicek. Banyak contoh memakai master, tetapi tim produksi sering memakai production, staging, atau environment alias. Token yang bisa membaca master belum tentu punya akses ke environment lain. Locale juga tidak selalu sama: bisa id-ID, en-US, atau konfigurasi internal. Semua fungsi fetch harus menerima parameter locale.

Client Contentful dengan tipe

Pilih token dan host di satu tempat. Page hanya mengirim preview dan locale.

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

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

Untuk model yang lebih besar, generate TypeScript types dari Contentful dan gunakan CI untuk mendeteksi drift. Prinsipnya tetap sama: content type ID, field ID, locale, dan status preview tidak boleh tersebar tanpa kontrol di banyak komponen.

Next.js dan Astro punya peran berbeda

Next.js cocok saat preview dan revalidasi on-demand penting. Halaman publish bisa statis, draft bisa memakai Draft Mode dengan Preview API, dan webhook Contentful bisa memanggil route yang menjalankan revalidatePath. Cek dokumentasi resmi sesuai versi: draftMode dan revalidatePath. Jangan asal menyalin contoh lama.

Astro cocok untuk output statis yang stabil. Ambil entries di getStaticPaths, lalu render HTML saat build. Konsekuensinya, perubahan di Contentful tidak otomatis mengubah HTML yang sudah deploy. Gunakan webhook untuk memicu rebuild platform, atau pisahkan halaman yang sering berubah ke Next.js ISR. Blog dan dokumentasi biasanya nyaman di Astro SSG, sedangkan landing page yang sering diedit lebih cocok memakai ISR.

Checklist kesalahan sebelum publish

Kesalahan	Gejala	Perbaikan
Preview token ke Delivery host	401 atau draft tidak muncul	pakai preview.contentful.com
Delivery token untuk draft	halaman preview null	pakai Content Preview API
Management token terekspos	kebocoran secret serius	batasi ke script/CI
Locale tidak dikirim	bahasa salah atau field kosong	kirim locale di setiap query
Asset belum publish	teks ada, gambar hilang	publish entry dan asset
Webhook setiap save	cache produksi sering kosong	gunakan publish/unpublish
Field ID diganti	type dan render rusak	pertahankan API identifier

Validasi akhir jangan hanya di next dev. Uji build, preview URL, webhook, dan route locale. Minta Claude Code membuat tabel token, host, locale, dan path untuk route penting. Tabel kecil ini sering menemukan konfigurasi yang salah.

Hubungkan CMS dengan monetisasi

Integrasi CMS juga harus mendukung jalur pendapatan. Jangan sembunyikan semua CTA di Rich Text. Buat field seperti ctaKind, ctaLabel, ctaUrl, dan relatedPosts. Artikel teknis bisa mengarah ke cheatsheet gratis, artikel adopsi tim ke training and consultation, dan konten template ke products.

Struktur ini membuat analytics lebih rapi. Event cta_click punya ID stabil, editor bisa mengubah copy tanpa menyentuh komponen, dan Claude Code bisa mereview kontrak antara Contentful dan UI. Saat diuji, pemisahan Delivery, Preview, dan Management sejak prompt awal membuat diff lebih kecil, kesalahan locale lebih mudah terlihat, dan masalah preview bisa diperbaiki sebelum deploy.