Интеграция 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 уже сегодня.