How to Integrate Bolt.new with Ghost

Ghost's API keys are created through Custom Integrations in Ghost Admin. This is different from most platforms — there is no developer portal or OAuth flow. You create an integration once, and Ghost generates both a Content API key and an Admin API key for that integration. Log in to your Ghost Admin panel at `your-ghost-url/ghost`. Navigate to Settings (gear icon in the bottom-left sidebar) → Integrations → scroll to the 'Custom Integrations' section at the bottom → click 'Add custom integration.' Give it a name (e.g., 'Bolt Dashboard' or 'BoltApp Frontend') and click 'Create.' Ghost immediately generates two keys: The Content API Key is a hex string (like `a9b8c7d6e5f43210abcdef12`). It provides read-only access to your published content. This key is safe to use in client-side JavaScript — it can only read public content, not modify anything or access private drafts. The Admin API Key is formatted as `{keyId}:{secret}` (like `5abb6d...abcdef:3ef56a...`). It provides full read-write access including drafts, members, and administrative operations. This key must remain server-side and should never appear in client-side code or be committed to your repository. Also note your Ghost URL — the base domain of your Ghost instance. For Ghost(Pro), this is typically `https://yoursite.ghost.io` or your custom domain if configured. For self-hosted Ghost, it is whatever domain you pointed at the server. Add three values to your Bolt project's .env file: `GHOST_URL=https://your-ghost-url.ghost.io`, `GHOST_CONTENT_API_KEY=your-content-api-key`, and `GHOST_ADMIN_API_KEY=your-admin-api-key` (if you need write access). The GHOST_URL is also needed as a public variable for client components: `NEXT_PUBLIC_GHOST_URL=https://your-ghost-url.ghost.io`.

1// lib/ghost.ts
2const GHOST_URL = process.env.GHOST_URL;
3const GHOST_CONTENT_API_KEY = process.env.GHOST_CONTENT_API_KEY;
4
5interface GhostFetchOptions {
6  params?: Record<string, string>;
7}
8
9export async function ghostFetch<T = unknown>(
10  endpoint: string,
11  options: GhostFetchOptions = {}
12): Promise<T> {
13  if (!GHOST_URL || !GHOST_CONTENT_API_KEY) {
14    throw new Error('GHOST_URL and GHOST_CONTENT_API_KEY must be set in .env');
15  }
16
17  const url = new URL(`${GHOST_URL}/ghost/api/content/${endpoint}/`);
18  url.searchParams.set('key', GHOST_CONTENT_API_KEY);
19
20  if (options.params) {
21    Object.entries(options.params).forEach(([k, v]) => url.searchParams.set(k, v));
22  }
23
24  const response = await fetch(url.toString());
25  const data = await response.json() as { errors?: Array<{ message: string; context?: string }> } & T;
26
27  if (!response.ok || data.errors) {
28    const message = data.errors?.[0]?.message || `Ghost API error: ${response.status}`;
29    throw new Error(message);
30  }
31
32  return data;
33}
34
35export interface GhostPost {
36  id: string;
37  uuid: string;
38  title: string;
39  slug: string;
40  html: string;
41  excerpt: string;
42  custom_excerpt: string | null;
43  feature_image: string | null;
44  feature_image_alt: string | null;
45  reading_time: number;
46  published_at: string;
47  updated_at: string;
48  tags: Array<{ id: string; name: string; slug: string; description: string | null }>;
49  authors: Array<{ id: string; name: string; slug: string; profile_image: string | null }>;
50  meta_title: string | null;
51  meta_description: string | null;
52  og_image: string | null;
53  twitter_image: string | null;
54  primary_tag: { id: string; name: string; slug: string } | null;
55  primary_author: { id: string; name: string; slug: string; profile_image: string | null };
56}
57
58export async function ghostPosts(
59  params?: Record<string, string>
60): Promise<{ posts: GhostPost[]; meta: { pagination: { page: number; pages: number; limit: number; total: number } } }> {
61  return ghostFetch('posts', {
62    params: {
63      include: 'tags,authors',
64      fields: 'id,title,slug,html,excerpt,custom_excerpt,feature_image,feature_image_alt,reading_time,published_at,updated_at,primary_tag,primary_author,meta_title,meta_description',
65      ...params,
66    },
67  });
68}
69
70export async function ghostPost(slug: string): Promise<{ posts: GhostPost[] }> {
71  return ghostFetch('posts', {
72    params: {
73      filter: `slug:${slug}`,
74      include: 'tags,authors',
75      limit: '1',
76    },
77  });
78}
79
80export async function ghostTags(): Promise<{ tags: Array<{ id: string; name: string; slug: string; description: string | null; count: { posts: number } }> }> {
81  return ghostFetch('tags', {
82    params: { include: 'count.posts', limit: 'all' },
83  });
84}

Ghost's Content API is one of the most developer-friendly CMS APIs available. Posts are returned with full HTML content, semantic metadata, author information, and tag relationships in a single request. The API supports powerful filtering, ordering, and pagination built into the query parameters. The posts endpoint is `GET /ghost/api/content/posts/`. Key parameters: `key` (your Content API key, required), `include` (related data to embed: tags, authors, tiers), `fields` (specific fields to return — use this to reduce response size), `limit` (number of posts, default 15, max 15 for Ghost API key tier, 'all' for unlimited), `page` (page number for pagination), `filter` (NQL-based filtering), and `order` (sorting). Ghost uses Nested Query Language (NQL) for filtering, which is more powerful than simple equality matching. Examples: `filter=tag:technology` (posts with a specific tag), `filter=featured:true` (featured posts only), `filter=published_at:>2024-01-01` (posts after a date), `filter=tag:technology+featured:true` (AND condition), `filter=tag:technology,tag:design` (OR condition). This filtering capability enables building dynamic tag pages, featured sections, and date-range archives without additional client-side filtering. For a blog listing page, a good default request includes: `include=tags,authors` (to display tag badges and author names without separate API calls), `fields` limited to non-body fields (exclude the `html` field on listing pages since it can be large), `limit=12` (a page-appropriate number for grid layouts), and `order=published_at desc` (newest first). For individual post pages, fetch the full post with `html` included and render it inside a prose-styled container. Ghost generates clean semantic HTML with proper heading hierarchy, code blocks with language classes, and responsive images. Apply Tailwind's `prose` class from `@tailwindcss/typography` to the container for attractive default text styling without writing custom post CSS.

1// app/api/ghost/posts/route.ts
2import { NextResponse } from 'next/server';
3import { ghostPosts } from '@/lib/ghost';
4
5export async function GET(request: Request) {
6  const { searchParams } = new URL(request.url);
7  const page = searchParams.get('page') || '1';
8  const limit = searchParams.get('limit') || '12';
9  const tag = searchParams.get('tag');
10
11  const params: Record<string, string> = {
12    page,
13    limit,
14    order: 'published_at desc',
15    fields: 'id,title,slug,excerpt,custom_excerpt,feature_image,feature_image_alt,reading_time,published_at,primary_tag,primary_author',
16  };
17
18  if (tag) {
19    params.filter = `tag:${tag}`;
20  }
21
22  try {
23    const data = await ghostPosts(params);
24    return NextResponse.json({
25      posts: data.posts,
26      pagination: data.meta.pagination,
27    });
28  } catch (err) {
29    const message = err instanceof Error ? err.message : 'Failed to fetch posts';
30    return NextResponse.json({ error: message }, { status: 500 });
31  }
32}
33
34// app/api/ghost/posts/[slug]/route.ts
35// import { NextResponse } from 'next/server';
36// import { ghostPost } from '@/lib/ghost';
37// export async function GET(_req: Request, { params }: { params: { slug: string } }) {
38//   try {
39//     const data = await ghostPost(params.slug);
40//     if (!data.posts?.[0]) return NextResponse.json({ error: 'Post not found' }, { status: 404 });
41//     return NextResponse.json({ post: data.posts[0] });
42//   } catch (err) {
43//     return NextResponse.json({ error: 'Failed to fetch post' }, { status: 500 });
44//   }
45// }

With the Ghost API routes returning structured post data, build the React components that render your blog. A well-designed headless Ghost frontend typically has three main views: a post listing page (home page or /blog), individual post pages, and tag/category pages. For the post listing page, create a PostCard component that renders a post's feature image, title, excerpt, reading time, publish date, primary tag badge, and author avatar. Ghost provides `reading_time` as a pre-calculated integer (minutes), `primary_tag` as the first tag, and `primary_author` as the first author — convenient for card layouts without complex data manipulation. Format dates using JavaScript's `Intl.DateTimeFormat` for locale-aware display. For individual post pages, the most important consideration is rendering Ghost's HTML output safely. Ghost generates clean, well-structured HTML, but Next.js's `dangerouslySetInnerHTML` prop is required to render it. The risk is minimal since the HTML comes from your own Ghost instance (not user input), but follow the practice of wrapping the content in a styled container. Apply Tailwind's prose classes from the `@tailwindcss/typography` plugin for beautiful typographic defaults: `<div className="prose prose-lg max-w-none" dangerouslySetInnerHTML={{ __html: post.html }} />`. Ghost's HTML includes images with responsive `srcset` attributes, code blocks with `language-*` class names for syntax highlighters, blockquotes, and properly nested heading hierarchies. The typography plugin handles all of these correctly. For tag pages, create a `/tag/[slug]` route that fetches the tag details from Ghost's tags endpoint and the filtered posts list. Ghost's tag objects include a `description` (the tag's bio) and `feature_image` which you can use as the tag page header image.

Ghost's Admin API allows creating, updating, and deleting posts, pages, tags, and members programmatically. This is useful for building custom editorial workflows, importing content from other sources, or creating a simplified editing interface for non-technical team members. The Admin API uses JWT authentication rather than a simple API key. The Admin API key (format `{keyId}:{secret}`) must be split at the colon, and a JWT token must be constructed with the key ID in the header and the secret used to sign the payload. Ghost's official `@tryghost/admin-api` npm package handles this JWT complexity automatically. For creating a post via the Admin API, send a POST request to `/ghost/api/admin/posts/` with a JSON body containing at minimum `title` and `status` (draft or published). The `html` field accepts HTML content, and the `mobiledoc` field accepts Ghost's native editor format. Posts in draft status are accessible via the Admin API but not through the public Content API. Key considerations for Admin API use: all Admin API requests must be server-side since the API key grants full administrative access to your Ghost instance including member data, billing information, and settings. Never expose the Admin API key to client-side code. Also note that Admin API rate limits are more restrictive than Content API limits — Ghost throttles admin API calls to prevent abuse. For a Bolt app that only needs to display blog content, the Admin API is optional. Include it only if you are building content management features. The vast majority of Ghost integrations only need the Content API.

1// app/api/ghost/admin/posts/route.ts
2import { NextResponse } from 'next/server';
3// Note: @tryghost/admin-api is a CommonJS package — import with require
4import GhostAdminAPI from '@tryghost/admin-api';
5
6function getAdminClient() {
7  const url = process.env.GHOST_URL;
8  const key = process.env.GHOST_ADMIN_API_KEY;
9
10  if (!url || !key) {
11    throw new Error('GHOST_URL and GHOST_ADMIN_API_KEY must be configured');
12  }
13
14  return new GhostAdminAPI({ url, key, version: 'v5.0' });
15}
16
17export async function POST(request: Request) {
18  const body = await request.json() as {
19    title: string;
20    html?: string;
21    status?: 'draft' | 'published';
22    tags?: Array<{ name: string } | { slug: string }>;
23  };
24
25  const { title, html, status = 'draft', tags } = body;
26
27  if (!title) {
28    return NextResponse.json({ error: 'title is required' }, { status: 400 });
29  }
30
31  if (status !== 'draft' && status !== 'published') {
32    return NextResponse.json({ error: 'status must be draft or published' }, { status: 400 });
33  }
34
35  try {
36    const api = getAdminClient();
37    const post = await api.posts.add(
38      { title, html: html || '', status, tags: tags || [] },
39      { source: 'html' } // tell Ghost the content is HTML, not Mobiledoc
40    );
41
42    return NextResponse.json({
43      id: post.id,
44      url: post.url,
45      title: post.title,
46      status: post.status,
47      slug: post.slug,
48    }, { status: 201 });
49  } catch (err) {
50    const message = err instanceof Error ? err.message : 'Failed to create post';
51    return NextResponse.json({ error: message }, { status: 500 });
52  }
53}

Ghost's Content API works perfectly in Bolt's WebContainer preview since all communication is outbound HTTPS to your Ghost instance. The WebContainer limitation does not affect Ghost integration — there are no incoming webhooks in the basic read-only integration. You can build, test, and verify the entire blog frontend in Bolt's preview before deploying. The Admin API also works in the WebContainer since it is also outbound HTTPS. Test post creation, updating, and deletion in the preview. The only reason to deploy early is if you want to test Ghost's webhook notifications (Ghost sends POST requests to your URL when content is published), which require a publicly accessible server. For deployment, connect Netlify via Settings → Applications → Connect Netlify or click Publish to deploy to Bolt Cloud. Add server-side environment variables: `GHOST_URL` and `GHOST_CONTENT_API_KEY` (both safe without NEXT_PUBLIC_ since they are accessed from API routes, though Content API key is not sensitive), and `GHOST_ADMIN_API_KEY` (server-side only, no NEXT_PUBLIC_). For performance optimization in production, consider Next.js ISR (Incremental Static Regeneration) for blog pages. Ghost webhooks can trigger ISR revalidation when content is published. Configure a revalidation route that Ghost calls via its webhook settings on content update — this approach means pages are statically served until content changes, providing maximum performance without stale content. For a production blog, enable Next.js image optimization by using `next/image` with your Ghost URL in the `domains` config array in `next.config.js`. This enables automatic WebP conversion, responsive sizing, and lazy loading for Ghost's feature images.

1// next.config.js addition for Ghost image optimization:
2/** @type {import('next').NextConfig} */
3const nextConfig = {
4  images: {
5    domains: [
6      // Add your Ghost domain(s) here:
7      'your-publication.ghost.io',
8      // Also include Ghost's CDN if using Ghost(Pro):
9      'images.unsplash.com', // Ghost(Pro) uses Unsplash for stock images
10    ],
11    // Alternative for Next.js 12+: use remotePatterns for more control
12    remotePatterns: [
13      {
14        protocol: 'https',
15        hostname: '**.ghost.io',
16        pathname: '/content/images/**',
17      },
18    ],
19  },
20};
21
22module.exports = nextConfig;