Інтеграція 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 для вашого проєкту. Зв'яжіться з нами, щоб обговорити деталі та терміни.