Інтеграція Contentful із фронтендом (React/Next.js/Gatsby)

Уявіть: ваш редактор оновлює тип запису, а фронтенд починає сипати помилками — поля undefined, невірні дати, зламані білди. Без типізації кожна зміна контент-моделі перетворюється на НП. А якщо ще потрібно оновити зображення та Rich Text — час публікації розтягується на години. Ми вирішуємо це автоматичною генерацією типів, ISR-ревалідацією та оптимізованим рендерингом Rich Text. Наші інженери мають сертифікати Contentful та досвід 10+ проєктів — гарантуємо результат. Зв'яжіться з нами для демонстрації готового рішення.

Нещодавно до нас звернувся клієнт, у якого інтернет-магазин на Next.js гальмував через відсутність ISR та слабку типізацію. Після впровадження нашої інтеграції час завантаження сторінок скоротився в 3 рази, а помилки при публікації зникли.

Чому типізація Content Types економить дні розробки?

Ручне написання TypeScript-інтерфейсів для моделей Contentful — часта причина багів та розсинхронізації. Використовуємо cf-content-types-generator, який на основі Content Types автоматично генерує строго типізовані інтерфейси. Це скорочує час розробки на 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 з вебхуками без перебудови всього сайту?

ISR (Incremental Static Regeneration) оновлює сторінки на вимогу. Покроково:

1. Встановіть revalidate у Next.js (наприклад, 3600 секунд).
2. Створіть API-роут для вебхука, який викликає revalidatePath.
3. У Contentful налаштуйте вебхук на подію публікації запису.

Код клієнта та роута:

// 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. Для рендеру використовуємо @contentful/rich-text-react-renderer з кастомними вузлами. Це дозволяє вставляти зображення, код та посилання.

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 тис. записів (дані бенчмарків). Для великих проєктів з сотнями записів ми рекомендуємо використовувати пагінацію та кешування запитів на рівні BFF.

Що входить в роботу

• Налаштування клієнта Contentful та типізація всіх Content Types.
• Реалізація списку та сторінок для кожного типу контенту.
• Rich Text рендеринг з підтримкою вкладених посилань та зображень.
• ISR + on-demand регенерація через вебхуки.
• Preview mode (Draft Mode) для попереднього перегляду чернеток.
• Оптимізація зображень через Contentful Images API.
• Документація та навчання команди.

Кожен етап документується, щоб ваша команда могла самостійно підтримувати інтеграцію. Після завершення робіт ми надаємо детальну інструкцію з додавання нових типів контенту.

Строки типової інтеграції

Зверніть увагу: строки можуть варіюватися залежно від складності контент-моделей та необхідної функціональності.

Часті помилки та як їх уникнути

Гарантуємо підтримку після запуску: оновимо типи, виправимо баги, налаштуємо кешування. Зв'яжіться з нами, щоб обговорити ваш проєкт — отримайте консультацію та оцінку бюджету за 2 дні. Замовте інтеграцію Contentful вже сьогодні.