Інтеграція Contentful Headless CMS: від API до ISR

При розробці великого сайту на Next.js ми зіткнулися з проблемою: контент-менеджери не могли оперативно оновлювати сторінки. Кожна зміна вимагала перескладання проєкту – 15–20 хвилин простою. Рішення – headless CMS Contentful. Це хмарна платформа з потужною екосистемою SDK, розвиненим API та вбудованою мультимовністю. Контент зберігається в інфраструктурі Contentful, доступ – через Delivery API (публічний, кешований) та Management API (запис, приватний). Наш досвід – понад 30 впроваджень для клієнтів різного масштабу, від стартапів до enterprise. Базовий тариф Community безкоштовний, а Team – зі зростанням проєкту витрати збільшуються, але залишаються передбачуваними. Розберемо налаштування від А до Я за 5 днів. Замовте інтеграцію Contentful та прискорте публікацію контенту. Зв'яжіться з нами для обговорення вашого проєкту.

Які проблеми вирішує інтеграція Contentful

N+1 запити при отриманні пов'язаних сутностей. Стандартний REST API не дозволяє вибирати глибину підвантаження. Contentful вирішує це параметром include – за один запит можна отримати вкладені Entry та Asset. У прикладі нижче include: 2 завантажує автора та обкладинку для кожної статті.

import { createClient } from 'contentful';
const client = createClient({
  space: process.env.CONTENTFUL_SPACE_ID!,
  accessToken: process.env.CONTENTFUL_ACCESS_TOKEN!,
  environment: 'master',
});
const response = await client.getEntries<ArticleFields>({
  content_type: 'article',
  'fields.publishedAt[lte]': new Date().toISOString(),
  order: ['-fields.publishedAt'],
  limit: 10,
  locale: 'ru',
  include: 2,
});

Hydration mismatch під час SSR. Contentful Rich Text повертається як JSON AST, а не HTML. Використовуйте бібліотеку @contentful/rich-text-react-renderer для кастомного рендерингу без помилок гідрації.

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

const options = {
  renderNode: {
    [BLOCKS.EMBEDDED_ASSET]: (node) => {
      const { url, title } = node.data.target.fields.file;
      return <img src={`https:${url}`} alt={title} />;
    },
    [INLINES.HYPERLINK]: (node, children) => (
      <a href={node.data.uri} target="_blank" rel="noopener noreferrer">
        {children}
      </a>
    ),
    [BLOCKS.EMBEDDED_ENTRY]: (node) => {
      const entry = node.data.target;
      if (entry.sys.contentType.sys.id === 'codeBlock') {
        return <pre><code>{entry.fields.code}</code></pre>;
      }
    },
  },
};

Складність локалізації. Contentful зберігає локалізовані поля як словник {locale: value} в одному записі. Достатньо задати locale: '*' у запиті, щоб отримати всі мови одразу. Налаштування мультимовності займає 2–3 дні та підтримує до 5 мов у безкоштовному тарифі.

Як уникнути N+1 запитів при роботі з Contentful?

Проблема N+1 виникає, коли для кожного запису робиться окремий запит на пов'язані сутності. Contentful вирішує це через параметр include. Вкажіть глибину підвантаження – і всі пов'язані Entry та Asset повернуться в одній відповіді. У прикладі вище include: 2 підвантажує автора та обкладинку. Це скорочує кількість запитів з 11 до 1, що критично для LCP та TTFB. Наші клієнти відзначають прискорення завантаження сторінок до 40%.

Чому Contentful коштує дорожче, але вигідніше саморобного рішення?

Порівняємо з Directus (self-hosted) та Sanity у таблиці:

Якщо бюджет обмежений, Directus або Sanity – хороша альтернатива. Але для production-проєктів з командою Contentful дає готові рішення для ролей, середовищ та вебхуків. Економія часу на підтримку саморобного рішення становить до 60%, а середній ROI – 300% за рік.

Як налаштувати Contentful?

1. Створіть Space у панелі керування Contentful.
2. Визначте Content Types: наприклад, стаття, автор, категорія. Використовуйте Management API для автоматизації.
3. Налаштуйте Delivery API та Preview API. Отримайте токени доступу.
4. Встановіть SDK: npm install contentful для Next.js.
5. Напишіть запити з параметрами include, locale, order.
6. Налаштуйте Webhooks для ISR: при публікації контенту надсилайте POST на /api/revalidate.
7. Протестуйте всі кейси: публікація, чернетки, мультимовність, помилки.

Webhooks для ISR (Incremental Static Regeneration)

Space Settings -> Webhooks -> Add Webhook
Name: Next.js Revalidation
URL: https://example.com/api/revalidate
Events: Entry.publish, Entry.unpublish, Asset.publish

// app/api/revalidate/route.ts
export async function POST(req: Request) {
  const body = await req.json();
  const contentType = body.sys?.contentType?.sys?.id;
  if (contentType === 'article') {
    await revalidatePath('/blog');
    await revalidatePath(`/blog/${body.fields?.slug?.['en-US']}`);
  }
  return Response.json({ revalidated: true });
}

Гарантії стабільної роботи при масштабуванні

Contentful підтримує rate limiting (1000 запитів/хв на Community-тарифі), тому для високонавантажених проєктів налаштовується CDN-кешування та ISR. Ми використовуємо патерн BFF (Backend For Frontend) для агрегації даних та мінімізації запитів до API. Рекомендуємо також додати fallback-сторінки та моніторинг помилок. Налаштування економить до 40% часу на публікацію контенту.

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

• Проектування моделей контенту (Content Types) з урахуванням SEO та локалізації
• Готова інтеграція SDK з фреймворком (Next.js, Gatsby, React)
• Налаштування Delivery API, Preview API та Management API
• Реалізація Webhooks для автоматичної ревалідації (ISR)
• Документація щодо моделей та доступів
• Навчання команди (1–2 сесії)
• Підтримка протягом 30 днів після запуску

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