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