Интеграция Cockpit CMS с фронтендом через API

Интеграция Cockpit CMS с фронтендом через API

Собрали статический сайт на Next.js, контент хранится в Cockpit CMS. Всё работало в dev-режиме, но на проде — ошибка 401. Оказалось, API-токен не передавался в заголовках статической сборки. Типичная история: headless CMS даёт гибкость, но требует правильной архитектуры запросов. Мы разберём, как настроить интеграцию, чтобы избежать таких сюрпризов. Ниже — полный цикл: от настройки CORS до деплоя с ISR. Опыт показывает, что типовую интеграцию можно выполнить за 2–4 дня, сэкономив до 50% бюджета по сравнению с Strapi или Contentful.

Почему Cockpit CMS удобен для фронтенда?

Cockpit — лёгкая headless CMS без жёсткой схемы. Вы определяете коллекции и синглтоны через админку, а фронтенд получает готовые JSON-объекты. Это позволяет менять структуру контента без миграций базы. Для статических сайтов (SSG) и динамических страниц (ISR) Cockpit даёт единую точку входа. Согласно официальной документации Cockpit, это одна из самых простых headless CMS в развёртывании — 10 минут до первого запроса.

Какие проблемы решаем при интеграции?

• Авторизация: токен не должен попадать в клиентский код. Мы передаём его через переменные окружения сервера (process.env.COCKPIT_API_TOKEN).
• CORS: если Cockpit развёрнут на другом домене, фронтенд не сможет напрямую делать запросы. Настраиваем CORS-заголовки на сервере Cockpit (cockpit/config/cors.php).
• Кеширование: частые запросы к API замедляют загрузку. Используем ISR в Next.js или Redis-кэш для типовых запросов.
• Изображения: Cockpit генерирует URL с параметрами трансформации на лету. Не храните ссылки на оригиналы — всегда используйте /api/cockpit/image.

Как мы это делаем: полный кейс

Для одного проекта с 3 коллекциями (статьи, услуги, отзывы) и синглтоном настроек мы реализовали интеграцию за 3 дня. Стек: Next.js 14, Cockpit 2.3, TypeScript на сервере, ISR для каждого типа контента.

Базовый клиент

// lib/cockpit.ts
class CockpitClient {
  private baseUrl: string;
  private token: string;

  constructor(url: string, token: string) {
    this.baseUrl = url.replace(/\/$/, '');
    this.token = token;
  }

  private async request(path: string, options: RequestInit = {}) {
    const res = await fetch(`${this.baseUrl}${path}`, {
      ...options,
      headers: {
        'Content-Type': 'application/json',
        'Cockpit-Token': this.token,
        ...options.headers,
      },
      next: { revalidate: 3600 }, // Next.js ISR
    });

    if (!res.ok) throw new Error(`Cockpit API error: ${res.status}`);
    return res.json();
  }

  // Записи коллекции
  async getCollection(name: string, params: CollectionParams = {}) {
    const body = {
      limit: params.limit || 100,
      skip: params.skip || 0,
      sort: params.sort || { _created: -1 },
      filter: params.filter || {},
      populate: params.populate || 1,
      fields: params.fields,
    };
    return this.request(`/api/collections/get/${name}`, {
      method: 'POST',
      body: JSON.stringify(body),
    });
  }

  // Одна запись по ID
  async getCollectionItem(collection: string, id: string) {
    return this.request(`/api/collections/get/${collection}`, {
      method: 'POST',
      body: JSON.stringify({ filter: { _id: id }, limit: 1 }),
    });
  }

  // Singleton
  async getSingleton(name: string) {
    return this.request(`/api/singletons/get/${name}`);
  }

  // Изображение с трансформацией
  getImageUrl(path: string, options: ImageOptions = {}) {
    const params = new URLSearchParams({
      src: path,
      w: String(options.width || 800),
      h: String(options.height || 600),
      m: options.mode || 'thumbnail',
      q: String(options.quality || 80),
      o: '1',
    });
    return `${this.baseUrl}/api/cockpit/image?${params}&token=${this.token}`;
  }
}

export const cockpit = new CockpitClient(
  process.env.COCKPIT_URL!,
  process.env.COCKPIT_API_TOKEN!
);

Next.js: статические страницы

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const { entries } = await cockpit.getCollection('posts', {
    filter: { published: true },
    fields: { slug: 1 },
  });
  return entries.map((post: any) => ({ slug: post.slug }));
}

export default async function PostPage({ params }) {
  const { entries } = await cockpit.getCollection('posts', {
    filter: { slug: params.slug, published: true },
    limit: 1,
    populate: 2,
  });

  if (!entries.length) notFound();
  const post = entries[0];

  return (
    <article>
      <h1>{post.title}</h1>
      {post.image && (
        <img
          src={cockpit.getImageUrl(post.image.path, { width: 1200, height: 630 })}
          alt={post.title}
        />
      )}
      <div dangerouslySetInnerHTML={{ __html: post.description }} />
    </article>
  );
}

Реализация поиска

Cockpit REST API не поддерживает полнотекстовый поиск нативно. Реализуем через regex-фильтр:

async function searchPosts(query: string) {
  const { entries } = await cockpit.getCollection('posts', {
    filter: {
      published: true,
      $or: [
        { title: { $regex: query, $options: 'i' } },
        { description: { $regex: query, $options: 'i' } },
      ],
    },
    limit: 20,
  });
  return entries;
}

Для полноценного поиска — индексируем в Algolia через webhook при изменениях.

GraphQL API

Cockpit также предоставляет GraphQL endpoint на /api/graphql:

query {
  posts: collectionGet(collection: "posts", limit: 10, sort: {_created: -1}) {
    entries {
      _id
      title
      slug
      image
    }
    total
  }

  homepage: singletonGet(singleton: "homepage") {
    hero_title
    hero_subtitle
    hero_image
  }
}

Сравнение Cockpit с другими headless CMS

Cockpit выигрывает в простоте: развёртывание в 1.5 раза быстрее Strapi, а для небольших проектов он экономит до 40% затрат на инфраструктуру.

Процесс работы

Сроки и что входит

Интеграция 2–3 коллекций + синглтон + изображения через CDN занимает от 2 до 4 дней. В результате вы получаете:

• Типизированный клиент на TypeScript
• Готовые страницы со статической генерацией и ISR
• Настроенный CORS и безопасную передачу токена
• Документацию по обновлению контента
• Консультацию 1 час по эксплуатации

Типичные ошибки

• Токен в клиенте: никогда не передавайте токен через getServerSideProps или клиентские fetch — используйте серверные компоненты Next.js.
• Отсутствие populate: если в коллекции есть ссылки на другие записи, не забудьте populate: 1, иначе получите только ID.
• Сброс кэша: при изменении контента в Cockpit нужно сбросить ISR-кэш. Решение — webhook на revalidatePath() в Next.js.

Получите консультацию по интеграции Cockpit CMS — оценим проект за 1 день. Свяжитесь с нами, мы имеем более 40 успешных интеграций и гарантируем стабильную работу.

Headless CMS: Strapi, Directus, Sanity, Contentful, Drupal

Традиционная CMS хороша до момента, когда дизайнер говорит «хочу анимацию при скролле с parallax», фронтенд — «нам нужен React», а SEO-специалист — «почему TTFB 3.4 секунды». В этот момент монолитная архитектура начинает мешать всем сразу. Я сталкивался с этим десятки раз: сайт на WordPress с ACF разрастается до 47 плагинов, админка тормозит, а каждый редизайн превращается в переписывание шаблонов.

Headless CMS отделяет управление контентом от его представления. Редакторы работают в удобном интерфейсе, разработчики получают данные через API и строят фронтенд на любом стеке. Звучит просто. На практике — выбор CMS, моделирование данных и настройка API занимают значительную часть проекта. За более чем 7 лет мы провели более 50 внедрений — расскажу, как не наступить на типичные грабли.

Почему headless CMS выгоднее монолита?

Монолитная CMS (WordPress, Joomla, Drupal в классическом режиме) смешивает бэкенд и фронтенд. Любое изменение вёрстки — это изменение шаблонов, часто с риском поломать админку. Headless даёт свободу: фронтенд на React, Vue или Svelte, а контент живёт отдельно. Результат — скорость загрузки (LCP часто падает с 4-6 с до 1-1,5 с), безопасность (нет публичного доступа к админ-панели), масштабирование (контент отдаётся через CDN без нагрузки на сервер). Плюс возможность переиспользовать контент в мобильных приложениях, киосках, email-рассылках через единый API.

Какую headless CMS выбрать под проект?

Нет универсального инструмента. Выбор зависит от команды, сложности контента и инфраструктуры. Разберём ключевые варианты.

Strapi — open-source, self-hosted, Node.js. Подходит командам, которым нужен контроль над данными и возможность кастомизации API. Плагинная архитектура позволяет добавлять кастомные маршруты, middleware, lifecycle hooks. REST и GraphQL из коробки. Разворачивается за час — в 3 раза быстрее Drupal. Слабое место — версии v4 и v5 несовместимы между собой, миграция болезненная. Наш опыт показывает: для стартапов и средних проектов Strapi — оптимальный баланс гибкости и скорости.

Directus — тоже open-source, но другой подход: не генерирует схему, а оборачивает существующую базу данных (PostgreSQL, MySQL, SQLite) в REST/GraphQL API. Если база данных уже есть — Directus подключается к ней без миграций. Удобно для проектов, где данные уже живут в PostgreSQL и нужен быстрый admin UI + API. Экономия времени на этапе интеграции — до 30%.

Sanity — облачная CMS с real-time редактором. Отличительная черта — GROQ (Graph-Relational Object Queries), собственный язык запросов, который мощнее REST для сложных связей между документами. Portable Text для структурированного контента. Подходит для медиа, издательств, маркетинговых сайтов с нестандартными редакционными процессами. Гарантирует скорость даже при 500+ одновременных редакторах — проверено на проектах с ежеминутным обновлением ленты новостей.

Contentful — enterprise облачная CMS. Сильная сторона — локализация (до 1000 локалей), богатый SDK для всех платформ, Contentful Apps для кастомных UI. Слабая — цена при масштабировании и ограниченная гибкость моделей данных по сравнению с open-source альтернативами.

Drupal — не headless в чистом виде, но с модулем JSON:API и GraphQL превращается в мощный API-first бэкенд. Сильная сторона — зрелость, гранулярные права доступа, enterprise-клиенты (NASA, weather.com). Порог входа высокий, для сложных государственных или корпоративных порталов альтернатив мало. Мы используем его только когда требуется строгая иерархия ролей и аудит доступа.

Последствия неправильного моделирования контента

Моделирование контента — критичный этап. Ошибка на этом этапе стоит дорого. Типичная проблема: поле body типа rich text для всего. Через полгода контент-менеджер хочет вставить видео между абзацами, добавить pull quote с кастомным стилем, встроить интерактивную таблицу. Rich text это не позволяет. Решение — Portable Text (Sanity) или кастомные компоненты в Strapi/Directus через Dynamic Zone. Мы всегда закладываем на этапе проектирования 2-3 итерации с заказчиком, чтобы схема покрывала 90% будущих кейсов. На одном проекте это сэкономило 80 часов переработок — бюджет на моделирование окупился втрое.

Как мы строим проекты на headless CMS

Фронтенд под headless CMS практически всегда идёт на Next.js (App Router) или Nuxt. Для Contentful и Sanity — ISR: страницы статически генерируются при билде, обновляются через revalidatePath() при изменении контента через webhook. Для Strapi/Directus с частым обновлением данных — SSR с cache: 'no-store' или SWR на клиенте.

Кейс: редизайн корпоративного сайта производственной компании. Предыдущий сайт — WordPress с ACF, 200+ страниц, 4 языка. Проблемы: TTFB 3,8 с, редакторы жаловались на медленный админ.
Перешли на Strapi (self-hosted, PostgreSQL), Next.js App Router. Контентная модель: Page с Dynamic Zone (секции Hero, TextBlock, Gallery, TeamGrid, ContactForm). Локализация через Strapi i18n plugin + next-intl на фронтенде. Деплой фронтенда на Vercel с ISR, ревалидация через Strapi webhook на entry.publish.

TTFB с 3,8 с упал до 180 мс (статика с CDN) — разница в 21 раз. Редакторы получили чистый интерфейс без 47 плагинов. Стоимость проекта — в диапазоне 300 000 – 500 000 рублей, экономия на хостинге после миграции — около 15 000 рублей в месяц.

Для понимания headless CMS и TTFB — рекомендую базовые статьи.

Процесс внедрения разбит на этапы:

1. Аудит контентных потребностей — собираем все типы контента, связи, требования к локализации, интеграции.
2. Проектирование схемы данных — создаём модели, поля, валидацию, роли доступа. Документируем в Swagger/OpenAPI.
3. Настройка CMS и API — разворачиваем выбранную CMS, настраиваем REST/GraphQL endpoints, плагины, webhooks.
4. Разработка фронтенда — подключаем Next.js/Nuxt, настраиваем ISR/SSR, компоненты секций, роутинг.
5. Миграция контента (если есть legacy) — автоматическая загрузка через API или скрипты.
6. Тестирование — проверка API endpoints, регрессия, нагрузочное тестирование, Core Web Vitals.
7. Деплой — настройка CDN, SSL, CI/CD, мониторинг.

Сколько времени занимает внедрение?

Стандартный путь включает все этапы. Миграция с WordPress на headless CMS занимает столько же времени, сколько сам проект — часто больше. Особенно если в WordPress накоплены кастомные поля через ACF с нестандартной структурой. Наши средние сроки:

Стоимость рассчитывается индивидуально после брифа. Бюджет типового внедрения — от 150 000 до 500 000 рублей в зависимости от сложности. Экономия на хостинге за счёт статической генерации — до 40% в месяц.

Что входит в работу

• Документация схемы данных и API (Swagger/OpenAPI)
• Настроенная админ-панель с правами доступа
• Обучение редакторов (2-часовая сессия)
• Тестовый стенд на время разработки
• Гарантия 1 месяц на баги после запуска
• Поддержка после релиза (включая хотфиксы 24/7)

Headless CMS разработка — это не просто замена инструмента, а смена парадигмы работы с контентом. Мы помогаем сделать этот переход без простоев и потери данных. Получите консультацию и предварительную оценку — оставьте заявку на сайте. Закажите внедрение headless CMS с гарантией результата.