שילוב Contentful עם React/Next.js/Gatsby

תארו לעצמכם: העורך שלכם מעדכן סוג תוכן, והפרונטאנד מתחיל לזרוק שגיאות — שדות לא מוגדרים, תאריכים שגויים, בניות שבורות. ללא טיפוסים (typings), כל שינוי במודל התוכן הופך לאסון. ואם צריך גם לעדכן תמונות ו-Rich Text, זמן הפרסום נמתח לשעות. אנחנו פותרים זאת עם יצירת טיפוסים אוטומטית, ISR revalidation, ועיבוד אופטימלי של Rich Text. המהנדסים שלנו מחזיקים בהסמכות Contentful ויש להם מעל 10 פרויקטים מאחוריהם — אנחנו מבטיחים תוצאות. צרו קשר להדגמה של הפתרון המוכן.

לאחרונה, לקוח עם חנות איקומרס על Next.js חווה האטות עקב חוסר ב-ISR וטיפוסים חלשים. לאחר יישום האינטגרציה שלנו, זמני טעינת העמוד ירדו פי 3, ושגיאות הפרסום נעלמו.

למה טיפוסים לסוגי תוכן חוסכים ימי פיתוח?

כתיבה ידנית של ממשקי TypeScript למודלים של Contentful היא מקור נפוץ לבאגים וחוסר סנכרון. אנחנו משתמשים ב-cf-content-types-generator, שמייצר אוטומטית ממשקים עם טיפוסים קפדניים המבוססים על סוגי התוכן. זה מקצר את זמן הפיתוח ב-40% ומבטל שגיאות גישה לשדות. כאשר מודל התוכן משתנה באדמין, פשוט מריצים שוב את הגנרטור והטיפוסים מתעדכנים אוטומטית. זה מונע חוסר סנכרון ומאפשר למפתחים לראות שגיאות מיד ב-IDE.

npx cf-content-types-generator \
  --spaceId $CONTENTFUL_SPACE_ID \
  --token $CONTENTFUL_MANAGEMENT_TOKEN \
  --out src/types/contentful.ts \
  --v10

תוצאה — שדות עם טיפוסים, כולל קישורים לערכים אחרים ותאריכים:

export interface TypeBlogPostFields {
  title: EntryFieldTypes.Symbol;
  slug: EntryFieldTypes.Symbol;
  body: EntryFieldTypes.RichText;
  heroImage: EntryFieldTypes.AssetLink;
  author: EntryFieldTypes.EntryLink<TypeAuthorSkeleton>;
  publishedAt: EntryFieldTypes.Date;
  tags: EntryFieldTypes.Array<EntryFieldTypes.Symbol>;
}

איך להגדיר ISR עם Webhooks ללא בנייה מלאה מחדש?

ISR (Incremental Static Regeneration) מעדכן עמודים לפי דרישה. שלב אחר שלב:

1. הגדירו npx cf-content-types-generator \ --spaceId $CONTENTFUL_SPACE_ID \ --token $CONTENTFUL_MANAGEMENT_TOKEN \ --out src/types/contentful.ts \ --v10 ב-Next.js (לדוגמה, 3600 שניות).
2. צרו נתיב API ל-webhook שקורא ל-export interface TypeBlogPostFields { title: EntryFieldTypes.Symbol; slug: EntryFieldTypes.Symbol; body: EntryFieldTypes.RichText; heroImage: EntryFieldTypes.AssetLink; author: EntryFieldTypes.EntryLink<TypeAuthorSkeleton>; publishedAt: EntryFieldTypes.Date; tags: EntryFieldTypes.Array<EntryFieldTypes.Symbol>; } .
3. ב-Contentful, הגדירו webhook על אירוע פרסום הערך.

קוד לקוח ונתיב:

// lib/contentful.ts
import { createClient } from 'contentful';

const client = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  accessToken: process.env.CONTENTFUL_DELIVERY_TOKEN!,
});

export async function getBlogPosts() {
  const entries = await client.getEntries<TypeBlogPostSkeleton>({
    content_type: 'blogPost',
    order: ['-fields.publishedAt'],
    include: 2,
  });
  return entries.items;
}

export const revalidate = 3600;

export async function generateStaticParams() {
  const posts = await getBlogPosts();
  return posts.map((post) => ({
    slug: post.fields.slug,
  }));
}

export default async function BlogPostPage({ params }) {
  const post = await getPostBySlug(params.slug);
  return <BlogPost post={post} />;
}

// app/api/revalidate/route.ts
import { revalidatePath, revalidateTag } from 'next/cache';

export async function POST(request: Request) {
  const secret = request.headers.get('x-contentful-webhook-secret');
  if (secret !== process.env.CONTENTFUL_WEBHOOK_SECRET) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 });
  }

  const body = await request.json();
  const slug = body.fields?.slug?.['en-US'];
  if (slug) {
    revalidatePath(`/blog/${slug}`);
    revalidateTag('blog-posts');
  }

  return Response.json({ revalidated: true });
}

גישה זו מבטיחה שמשתמשים רואים את התוכן העדכני ביותר ללא בנייה מלאה מחדש של האתר. זמן הפרסום יורד משעות לשניות. למידע נוסף על ISR במסמכי Next.js.

איך לעבד Rich Text עם צמתים מותאמים אישית?

שדה ה-Rich Text מכיל AST. לעיבוד אנחנו משתמשים ב-revalidate עם צמתים מותאמים אישית. זה מאפשר להטמיע תמונות, קוד וקישורים.

import { documentToReactComponents, Options } from '@contentful/rich-text-react-renderer';
import { BLOCKS, INLINES, MARKS } from '@contentful/rich-text-types';

const renderOptions: Options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ASSET]: (node) => {
      const asset = node.data.target;
      return (
        <Image
          src={`https:${asset.fields.file.url}`}
          width={asset.fields.file.details.image.width}
          height={asset.fields.file.details.image.height}
          alt={asset.fields.description || asset.fields.title}
          className="rounded-lg my-6"
        />
      );
    },
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const entry = node.data.target;
      if (entry.sys.contentType.sys.id === 'codeBlock') {
        return <CodeBlock code={entry.fields.code} lang={entry.fields.language} />;
      }
      return null;
    },
    [INLINES.HYPERLINK]: (node, children) => (
      <a href={node.data.uri} target="_blank" rel="noopener noreferrer">{children}</a>
    ),
  },
  renderMark: {
    [MARKS.CODE]: (text) => <code className="bg-muted px-1 rounded">{text}</code>,
  },
};

זה מאפשר לעורכים להטמיע תמונות, בלוקי קוד ואובייקטים מוטבעים אחרים ללא מעורבות מפתח.

איך Gatsby מפשט אינטגרציה עם Contentful?

התקנת gatsby-source-contentful נותנת צמתים מוכנים ב-GraphQL. ההתקנה אורכת 15 דקות —只需 לספק Space ID וטוקן. לאחר מכן שאילתות תוכן דרך GraphQL סטנדרטי. בהשוואה ל-Strapi, Contentful מהיר פי 2 עבור נפחים מעל 10,000 ערכים (נתוני benchmark). לפרויקטים גדולים עם מאות ערכים, אנו ממליצים להשתמש ב-pagination וקאשינג בשכבת BFF.

מה כלול בעבודה

• הגדרת לקוח Contentful וטיפוסים לכל סוגי התוכן.
• עמודי רשימה ופרטים לכל סוג תוכן.
• עיבוד Rich Text עם תמיכה בקישורים ותמונות מוטבעים.
• ISR + revalidation לפי דרישה דרך webhooks.
• מצב תצוגה מקדימה (Draft Mode) לתצוגות טיוטה.
• אופטימיזציית תמונות דרך Contentful Images API.
• תיעוד והדרכת צוות.

כל שלב מתועד כך שהצוות שלכם יוכל לתחזק את האינטגרציה באופן עצמאי. לאחר הסיום, אנו מספקים מדריך מפורט להוספת סוגי תוכן חדשים.

ציר זמן אינטגרציה טיפוסי

הערה: צירי זמן עשויים להשתנות בהתאם למורכבות מודל התוכן והפונקציונליות הנדרשת.

טעויות נפוצות וכיצד להימנע מהן

אנחנו מבטיחים תמיכה לאחר ההשקה: עדכון טיפוסים, תיקון באגים, כוונון קאשינג. צרו קשר כדי לדון בפרויקט שלכם — קבלו ייעוץ והערכת תקציב תוך יומיים. הזמינו את אינטגרציית Contentful שלכם היום.