Headless Ghost: Custom Frontend with Content API

Headless architecture with Ghost: from API to ready frontend

Handlebars themes in Ghost offer limited flexibility: any non-standard UI requires rewriting templates, and performance suffers due to server-side rendering without caching. Ghost Content API is a public read-only REST interface that allows separating the backend from the frontend. We use this approach in every headless project: the database and admin panel stay on Ghost, while the UI is built with Next.js, Astro, or Vue. The result is full control over design and Core Web Vitals at 90+.

What is Ghost Content API and how does it work?

Ghost Content API v5 provides access to content via standard HTTP requests. It returns JSON with posts, pages, tags, and authors. Unlike Handlebars, you get raw data and build the interface yourself. The API is optimized for reading: average response time is under 30 ms with 10,000 posts. Authentication is done via a public API key, which can safely be used on the frontend.

How does authentication work in Ghost Content API?

The Content API Key is created in Ghost Admin: Settings → Integrations → Add custom integration. The key is passed as a query parameter or header. It is public (read-only), so it can be used on the frontend without additional authorization.

// 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', }); 

Core methods of Ghost Content API

The SDK provides browse methods for lists and read for single records. It supports pagination, filters, field selection, and inclusion of related data (authors, tags). For a typical blog, posts.browse and posts.read are enough. Note the formats parameter: html or plaintext.

// List posts with pagination 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 } // Single post by slug const post = await ghostClient.posts.read( { slug: 'my-post-slug' }, { include: ['tags', 'authors'], formats: ['html', 'plaintext'] } ); // Pages, tags, authors, settings — similarly 

Next.js App Router integration

In the App Router, data is fetched in Server Components. ISR with revalidate allows cache updates without rebuilding. For list pages, generateStaticParams with limit: 'all' is convenient. This approach gives static site generation (SSG) with incremental updates.

// 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} />; } 

Render Ghost HTML with DOMPurify

Ghost returns ready HTML in the html field. For safe rendering, use DOMPurify sanitization and separate styles for Ghost cards. This approach works with React, Vue, and other frameworks.

// 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 for Ghost card elements is added separately: @/styles/ghost-cards.css (contains styles for kg-bookmark, kg-gallery, kg-video, etc.).

How to solve the Members API problem in headless mode?

Members functions (paywall, subscriptions) are more complex in headless mode. Ghost provides Portal — an iframe widget for sign-in. It can be embedded in any frontend.

<script src="https://myblog.com/public/member-attribution.min.js" async></script> <button onclick="window.location.href='https://myblog.com/#/portal/signup'">Subscribe</button> 

Full Members integration requires proxying sessions through Ghost API — this is justified only for commercial projects with subscriptions.

When should you choose headless architecture?

If your blog requires a unique UI, custom animations, or complex client-side logic, headless is the only way. Native Ghost themes are faster to develop but lose in flexibility and performance. Compare:

Ghost Content API paired with Next.js delivers Core Web Vitals at 90+. Ghost Content API is 30% faster than GraphQL solutions for simple queries (according to our tests with Apollo Client). Headless architecture reduces maintenance costs by 30–50% through component reuse. Contact us for a blog audit — we'll help estimate potential savings.

What is included in our work?

1. Audit of current architecture and requirements.
2. Content API setup and creation of necessary integrations.
3. Development of custom frontend on Next.js, Astro, or Vue.
4. Members Portal integration (if subscriptions are needed).
5. Cross-browser and performance testing.
6. Handover of API documentation and data structure.
7. 1-month warranty support after launch.

Estimated timelines

Get a consultation: tell us about your task, and we'll offer a transparent plan with a fixed timeframe. Investments in headless architecture pay off in 6–12 months through increased conversion and improved SEO.