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