Інтеграція 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 вже сьогодні.