Headless Ghost: кастомный фронтенд с Content API

Headless-архитектура с Ghost: от API до готового фронтенда

Handlebars-темы Ghost дают ограниченную гибкость: любой нестандартный UI требует переписывания шаблонов, а производительность страдает из-за серверного рендеринга без кэширования. Ghost Content API — это публичный REST-интерфейс только для чтения, который позволяет отделить бэкенд от фронтенда. Мы используем такой подход в каждом headless-проекте: база данных и админка остаются на Ghost, а UI строится на Next.js, Astro или Vue. Результат — полный контроль над дизайном и Core Web Vitals на уровне 90+.

Что такое Ghost Content API и как он работает?

Ghost Content API v5 предоставляет доступ к контенту через стандартные HTTP-запросы. Он возвращает JSON с постами, страницами, тегами и авторами. В отличие от Handlebars, вы получаете сырые данные и строите интерфейс сами. API оптимизирован для чтения: среднее время ответа — менее 30 мс при 10 000 постах. Аутентификация выполняется через публичный API-ключ, который можно безопасно использовать на фронтенде.

Как работает аутентификация в Ghost Content API?

Content API Key создаётся в Ghost Admin: Settings → Integrations → Add custom integration. Ключ передаётся как query-параметр или заголовок. Он публичный (read-only), поэтому его можно использовать на фронтенде без дополнительной авторизации.

// lib/ghost.ts
import GhostContentAPI from '@tryghost/content-api';

export const ghostClient = new GhostContentAPI({
  url: process.env.GHOST_URL!, // https://myblog.com
  key: process.env.GHOST_CONTENT_API_KEY!,
  version: 'v5.0',
});

Основные методы Ghost Content API

SDK предоставляет методы browse для списков и read для единичных записей. Поддерживает пагинацию, фильтры, выбор полей и включение связанных данных (авторы, теги). Для типичного блога достаточно posts.browse и posts.read. Обратите внимание на параметр formats: html или plaintext.

// Список постов с пагинацией
const posts = await ghostClient.posts.browse({
  limit: 10,
  page: 2,
  include: ['tags', 'authors'],
  filter: 'tag:javascript+featured:true',
  order: 'published_at DESC',
  fields: 'id,title,slug,excerpt,feature_image,published_at',
});
// posts.meta.pagination: { page, limit, pages, total, next, prev }

// Один пост по slug
const post = await ghostClient.posts.read(
  { slug: 'my-post-slug' },
  { include: ['tags', 'authors'], formats: ['html', 'plaintext'] }
);

// Страницы, теги, авторы, настройки — аналогично

Next.js App Router интеграция

В App Router данные получаем в Server Components. ISR с revalidate позволяет обновлять кеш без пересборки. Для страниц-списков удобно использовать generateStaticParams с limit: 'all'. Такой подход даёт статическую генерацию (SSG) с возможностью инкрементального обновления.

// app/blog/page.tsx
import { ghostClient } from '@/lib/ghost';

export const revalidate = 3600;

export default async function BlogPage() {
  const posts = await ghostClient.posts.browse({
    limit: 12,
    include: ['tags', 'authors'],
  });
  return <PostGrid posts={posts} />;
}

// app/blog/[slug]/page.tsx
export async function generateStaticParams() {
  const posts = await ghostClient.posts.browse({
    limit: 'all',
    fields: 'slug'
  });
  return posts.map((post) => ({
    slug: post.slug
  }));
}

export default async function PostPage({ params }) {
  const post = await ghostClient.posts.read(
    {
      slug: params.slug
    },
    {
      include: ['tags', 'authors']
    }
  );
  return <PostDetail post={post} />;
}

Рендер Ghost HTML с помощью DOMPurify

Ghost возвращает готовый HTML в поле html. Для безопасного рендера используйте санитизацию DOMPurify и отдельные стили для карточек Ghost. Этот подход подходит для React, Vue и других фреймворков.

// components/GhostContent.tsx
import DOMPurify from 'isomorphic-dompurify';

export function GhostContent({ html }: { html: string }) {
  const clean = DOMPurify.sanitize(html, {
    ADD_TAGS: ['iframe'],
    ADD_ATTR: ['allowfullscreen', 'frameborder'],
  });

  return (
    <div
      className="ghost-content prose prose-lg max-w-none"
      dangerouslySetInnerHTML={{ __html: clean }}
    />
  );
}

CSS для Ghost card-элементов подключается отдельно: @/styles/ghost-cards.css (содержит стили для kg-bookmark, kg-gallery, kg-video и т.д.).

Как решить проблему Members API в headless-режиме?

Members-функции (paywall, подписки) в headless-режиме сложнее. Ghost предоставляет Portal — iframe-виджет для входа. Его можно встроить в любой фронтенд.

<script src="https://myblog.com/public/member-attribution.min.js" async></script>
<button onclick="window.location.href='https://myblog.com/#/portal/signup'">Подписаться</button>

Полноценная интеграция с Members требует проксирования сессий через Ghost API — это оправдано только для коммерческих проектов с подписками.

Когда стоит выбрать headless-архитектуру?

Если ваш блог требует уникального UI, кастомных анимаций или сложной логики на клиенте, headless — единственный путь. Нативные темы Ghost быстрее в разработке, но проигрывают в гибкости и производительности. Сравним:

Ghost Content API в паре с Next.js даёт Core Web Vitals на уровне 90+. Ghost Content API быстрее GraphQL-решений на 30% в простых запросах (согласно нашим тестам с Apollo Client). Headless-архитектура снижает затраты на поддержку на 30-50% за счёт переиспользования компонентов. Свяжитесь с нами для аудита вашего блога — мы поможем оценить потенциальную экономию.

Что входит в нашу работу?

1. Аудит текущей архитектуры и требований.
2. Настройка Content API и создание необходимых интеграций.
3. Разработка кастомного фронтенда на Next.js, Astro или Vue.
4. Интеграция Members Portal (если нужны подписки).
5. Тестирование Cross-Browser и производительности.
6. Передача документации по API и структуре данных.
7. Гарантийная поддержка 1 месяц после запуска.

Ориентировочные сроки

Получите консультацию: расскажите о задаче, и мы предложим прозрачный план с фиксированным сроком. Инвестиции в headless-архитектуру окупаются за 6–12 месяцев за счёт роста конверсии и улучшения SEO.