Claude Code से Contentful CMS इंटीग्रेशन गाइड

पहले इंटीग्रेशन की सीमा तय करें

Contentful एक headless CMS है। इसका मतलब है कि editor Contentful में article, image, author, FAQ और CTA संभालते हैं, और frontend API से वही content लेकर Next.js या Astro में दिखाता है। Claude Code इस काम में तेज मदद कर सकता है, लेकिन अगर आप सिर्फ “Contentful जोड़ दो” कहेंगे तो अक्सर केवल एक published article दिखाने वाला demo बनेगा।

असल समस्या preview, locale, token और cache में आती है। Published English entry दिख जाती है, पर Hindi draft नहीं दिखता। Contentful में publish करने के बाद भी Next.js पुराना page दिखाता है। Image entry publish है, लेकिन asset publish नहीं है। इसलिए Claude Code को शुरुआत में ही बताना चाहिए कि कौन सी API किस काम के लिए है और कौन सा token browser में नहीं जाना चाहिए।

CMS की पूरी blog architecture के लिए Claude Code blog CMS पढ़ें। अगर CMS content को product API में भी भेजना है तो Claude Code API development उपयोगी है। Content से signup, training या consultation तक का रास्ता देखना हो तो content funnel audit भी देखें।

API और token अलग रखें

Contentful में तीन मुख्य API अलग-अलग काम करती हैं। Content Delivery API सिर्फ published content पढ़ती है। Content Preview API draft और unpublished changes पढ़ती है। Content Management API model, entry और publish operation के लिए है।

API	काम	token	सही जगह
Content Delivery API	published entry और asset पढ़ना	Delivery token	SSG, ISR, Server Component, Astro build
Content Preview API	draft और unpublished बदलाव देखना	Preview token	server-side preview route
Content Management API	content type बनाना, entry update, publish	Management token या PAT	local script, trusted CI
Images API	image resize और format बदलना	delivery/preview context	thumbnail, OGP, image helper

Official SDK में preview के लिए preview access token और host: "preview.contentful.com" इस्तेमाल होता है। Management API के Personal Access Token user permissions से जुड़े होते हैं, इसलिए उन्हें password की तरह संभालना चाहिए। References: Contentful JavaScript SDK, Personal Access Tokens, environment permissions और Astro Contentful guide।

Claude Code को साफ prompt दें

इस repo में Contentful blog integration implement करें।
- Published content के लिए सिर्फ Content Delivery API इस्तेमाल करें।
- Preview mode में ही Content Preview API इस्तेमाल करें।
- Content Management API token सिर्फ scripts/setup-contentful-model.ts में रहे।
- Default locale hi-IN है, en-US parameter से support हो।
- Next.js में Draft Mode और revalidatePath इस्तेमाल करें।
- Astro में getStaticPaths से build time पर entries fetch करें।
- Preview token और Management token browser में expose न हों।
- आखिर में changed files और verification commands बताएं।

ऐसा prompt Claude Code को code ही नहीं, boundaries भी देता है। अगर वह CONTENTFUL_PREVIEW_TOKEN को client component में डालता है, तो गलती तुरंत दिखती है। अगर draft पढ़ते समय cdn.contentful.com इस्तेमाल होता है, तो review में पकड़ आता है।

Use case के हिसाब से model बनाएं

Contentful की ताकत structured content है। सब कुछ एक Rich Text field में डालना आसान लगता है, लेकिन बाद में CTA, analytics, translation और search में दिक्कत होती है।

Use case	जरूरी fields	cache strategy	लक्ष्य
Tech blog	title, slug, excerpt, body, heroImage, author, tags, publishedAt	SSG + publish webhook	free PDF, related posts, training lead
Product landing page	headline, sections, pricingCopy, faq, ctaLabel, ctaUrl	छोटा ISR या manual revalidate	purchase, demo, consultation
Documentation	category, version, body, relatedDocs, updatedAt	SSG और search sync	paid support, templates
Localized news	locale-wise title/body, region, canonicalSlug	locale-wise build	regional CTA

एक test project में गलती यह थी कि blog और landing page दोनों को blogPost type में डाल दिया गया। Article ठीक था, लेकिन landing page को pricing, FAQ, CTA और experiment label चाहिए थे। Editor ने button copy को body में लिखना शुरू किया, जिससे click tracking मुश्किल हो गई। शुरुआत में model अलग रखना बेहतर है।

Environment variables और locale

.env.example बनाकर token roles साफ करें।

CONTENTFUL_SPACE_ID=your_space_id
CONTENTFUL_ENVIRONMENT=master
CONTENTFUL_DEFAULT_LOCALE=hi-IN
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 और Management token पर NEXT_PUBLIC_ prefix न लगाएं। Next.js में यह prefix value को browser bundle तक पहुंचा सकता है। Preview token unpublished content पढ़ सकता है और Management token space बदल सकता है। दोनों server route, local script या trusted CI में ही रहें।

Locale भी hardcode न करें। Hindi site में hi-IN हो सकता है, पर कोई team en-IN fallback या custom locale रख सकती है। हर fetch helper में locale parameter होना चाहिए, ताकि URL और Contentful entry एक ही भाषा पढ़ें।

Typed Contentful client

Token और host का चुनाव एक ही जगह रखें। Page सिर्फ यह बताए कि preview चाहिए या नहीं।

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

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

बड़ा project हो तो Contentful model से TypeScript types generate करें और CI में drift check करें। फिर भी नियम वही है: content type ID, field ID, locale और preview state components में बिखरे नहीं होने चाहिए।

Next.js और Astro का उपयोग

Next.js तब अच्छा है जब preview और on-demand revalidation चाहिए। Published pages static हो सकते हैं, drafts Draft Mode से Preview API पढ़ सकते हैं, और Contentful webhook revalidatePath चला सकता है। अपनी version के लिए draftMode और revalidatePath जरूर देखें।

Astro stable static pages के लिए अच्छा है। getStaticPaths में entries fetch करके build time पर HTML बनता है। लेकिन Contentful update होने पर deployed HTML अपने आप नहीं बदलता। Platform rebuild webhook लगाएं, या बार-बार बदलने वाली landing pages को Next.js ISR में रखें।

Publish से पहले failure check

गलती	लक्षण	fix
Preview token को Delivery host पर भेजना	401 या draft गायब	preview.contentful.com इस्तेमाल करें
Delivery token से draft पढ़ना	preview page null	Content Preview API इस्तेमाल करें
Management token browser में	गंभीर secret leak	सिर्फ scripts/CI
locale गायब	गलत भाषा या खाली field	हर query में locale
asset publish नहीं	text दिखे, image गायब	entry और asset दोनों publish
हर save पर webhook	cache बार-बार clear	publish/unpublish event

Testing सिर्फ next dev पर खत्म न करें। Production build, preview URL, webhook और locale route जांचें। Claude Code से आखिरी में token, host, locale और path की table बनवाएं।

CMS को revenue path से जोड़ें

CTA को Rich Text में छिपाने के बजाय ctaKind, ctaLabel, ctaUrl और relatedPosts जैसे fields रखें। Technical article free cheat sheet पर जा सकता है, team adoption article training and consultation पर, और template article products पर।

इस setup को test करने पर सबसे बड़ा सुधार token boundaries से आया। Delivery, Preview और Management अलग रखने पर Claude Code के diffs छोटे हुए, locale mistakes review में दिखीं और preview problems deploy से पहले ठीक हो गईं।