Add a blog to a Next.js site

The @kitful/next-blog package puts your Kitful posts on your own Next.js site, at /blog on your domain. You get:

• /blog, every post newest first
• A page for each post with its title, description, canonical link, social preview tags and structured data
• A blog sitemap at /blog/sitemap.xml
• A route that refreshes the cached pages seconds after you publish, update or delete a post

Posts are cached like static pages, so the blog loads as fast as the rest of your site. The package adds no styles of its own: posts take your site's typography.

Before you start

• A Next.js 16.3 or later app that uses the App Router. Cache Components can be on or off.
• Node.js 20.9 or later.
• A host that runs a Next.js server, such as Vercel. A static export (output: 'export') can't receive notifications.

Set it up

1. Connect Kitful

1. In Kitful, open Integrations inside your site and click Add on Headless.
2. Set the Blog URL to your site's address followed by /blog, such as https://example.com/blog. Kitful builds each post's address, canonical link and sitemap entry from it.
3. Set the Notification URL to your site's address followed by /api/kitful/revalidate, such as https://example.com/api/kitful/revalidate.
4. Click Connect and copy the Read token. Kitful shows it only once.

Connect a headless site explains every field.

2. Add the package and the blog files

If your app uses shadcn/ui and has a components.json, one command installs the package and copies the four blog files:

npx shadcn@latest add Kitful/next-blog/blog

Otherwise install the package:

npm install @kitful/next-blog

Then copy the four files from the example app into your app folder, keeping their paths. If your routes live in src/app, put them there.

The files are yours: wrap them in your layout and change the markup. The logic stays in the package, so npm update @kitful/next-blog brings fixes without touching your files.

3. Set the read token

Add the token to .env.local for local runs, and to your host's environment variables for the live site:

KITFUL_READ_TOKEN=kit_read_...

The build reads it too, so set it at your host before you deploy. Never give it a NEXT_PUBLIC_ name, which would send it to the browser, and never commit it.

4. Allow Kitful's image host

Featured images are served from img.kitful.ai. Add it to next.config.ts:

const nextConfig = {
  images: {
    remotePatterns: [new URL('https://img.kitful.ai/**')]
  }
};

export default nextConfig;

5. List the blog sitemap

Add /blog/sitemap.xml to the sitemaps in your robots.ts, so search engines find every post:

import type { MetadataRoute } from 'next';

export default function robots(): MetadataRoute.Robots {
  return {
    rules: { userAgent: '*', allow: '/' },
    sitemap: ['https://example.com/sitemap.xml', 'https://example.com/blog/sitemap.xml']
  };
}

If your site has no other sitemap, list only the blog one.

6. Deploy and test

1. Deploy the site.
2. In Kitful, click Manage on the headless destination and click Send test. Kitful reports Your site received the test notification.
3. Publish an article to the destination and open /blog on your site.

To look before you deploy, run npm run dev and open http://localhost:3000/blog. Kitful can't send notifications to your computer, so check the refresh on the deployed site.

How changes reach your site

Without a notification URL, cached pages refresh once a day.

A missing or deleted post shows your not-found page. With Cache Components on, Next.js sends it with status 200 and a noindex tag, which keeps it out of search results, and answers 404 to crawlers that read pages without streaming, such as Twitterbot. With Cache Components off, everyone gets 404.

Style the posts

<ArticleBody> prints the post's HTML (headings, paragraphs, lists, tables, images and code) with no classes. Style it through its className prop with your site's typography. With Tailwind CSS and its typography plugin, for example:

<ArticleBody post={post} className="prose" />

The post page renders the title as its only h1; the body starts at h2.

Set it up with an AI coding agent

In v0, Cursor, Claude Code or a similar tool, paste the prompt from the README's AI coding agent section. It installs the package, adds the four files and the image host, and tells you the notification URL to paste into Kitful. Set KITFUL_READ_TOKEN yourself at your host, and never paste it into the chat.

Hosting

• Vercel: nothing to configure.
• More than one server instance: a notification refreshes the cache of the instance that receives it. Configure a shared cache handler so every instance reads the same cache. Otherwise the others catch up within a day.
• Static export: not supported, since it has no server to receive notifications.

Another framework, or a site that keeps its own copy of the posts, reads them through the Blog API.

Troubleshoot

• The build fails with "KITFUL_READ_TOKEN is not set": add the variable at your host and build again. Locally, restart npm run dev after you edit .env.local.
• The build or a page fails with 401: the token is wrong, or it was replaced with New token. Click New token in Kitful and set the new token at your host.
• /blog is empty: publish an article to the headless destination. Only published posts show, and only those of the site the token belongs to.
• Send test reports 401: the site holds an old token. Set the current one and deploy again.
• Send test reports 404: the revalidate route is missing, or the notification URL has the wrong path.
• New posts or edits don't show: check the notification URL in Kitful and press Send test. An edit shows from the second visit. On several server instances, see Hosting.
• Images fail to load: add img.kitful.ai to images.remotePatterns, as in step 4.