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