Интеграция 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 успешных интеграций и гарантируем стабильную работу.