Publishing integrations

Add a Rankli blog to a Next.js site

For sites with no CMS at all. Instead of publishing into someone else’s database, your app reads the articles from ours through a blog-scoped key and revalidates on a schedule.

Install#

npm install @rankli/nextjs-blog
cp -r node_modules/@rankli/nextjs-blog/app/blog app/blog

Next.js 14 or newer with the App Router, React 18 or newer. The second line copies the starter routes into your app; they are yours to edit from then on.

Create the integration and get a key#

In Rankli, open Integrations → New integration → Next.js blog.
Name it after the site it serves.
Copy the API key from the confirmation. It is shown once.
Put it in your environment, locally and in your hosting provider’s settings:

.env.local

RANKLI_BLOG_API_KEY=rk_live_your_key_here
# Optional. The default is https://www.rankli.io/api/v1.
# RANKLI_API_URL=https://www.rankli.io/api/v1

The key is read on the server only, and it must not be prefixed NEXT_PUBLIC_. It is blog-scoped: it can read this site’s published posts and nothing else, so it is safe in a frontend deployment’s environment.

The routes#

The starter folder is four routes, each a thin page over the client:

Route	What it renders
/blog	The index, newest first, each card a link.
/blog/[slug]	One post: title, date, tags, hero image and the HTML Rankli rendered from the article.
/blog/tag/[slug]	Every post carrying a tag.
/blog/sitemap.xml	Every post and tag page, for search engines.

Each route exports revalidate from the client, and the post page names every slug in generateStaticParams, so the blog is static after the first build.

app/blog/[slug]/page.jsx, as shipped

import { getPost, listPosts, REVALIDATE } from '@rankli/nextjs-blog/client';

export const revalidate = REVALIDATE;

export async function generateStaticParams() {
  const posts = await listPosts();
  return posts.map((p) => ({ slug: p.slug }));
}

Your own layout#

The starter is deliberately unstyled beyond a readable measure. To build your own markup, import the client and drop the starter pages:

import {
  listPosts, getPost, listPostsByTag, listTags, tagSlug, configured, REVALIDATE,
} from '@rankli/nextjs-blog/client';

Export	Returns
listPosts({ limit, offset })	Posts, newest first. Each has id, title, slug, excerpt, meta_description, content_html, content_markdown, image_url, image_alt, tags and published_at.
getPost(slug)	One post, or null.
listPostsByTag(tag)	The posts carrying a tag.
listTags()	Every tag across the newest posts, with a URL-safe slug.
tagSlug(tag)	The slug the tag routes use.
configured()	Whether RANKLI_BLOG_API_KEY is set.
REVALIDATE	The ISR window in seconds, from RANKLI_BLOG_REVALIDATE.

Every function returns plain objects and never throws on a missing key: without one the list is empty and configured() says so, so a build never fails on a missing variable.

Caching and freshness#

Revalidation is daily by default: one request to us per page per day, and a blog that keeps serving if we are unreachable. Set RANKLI_BLOG_REVALIDATE in seconds to change the window; an article that publishes appears on your site within that window, or on your next deploy.

.env

RANKLI_BLOG_REVALIDATE=3600   # once an hour

When it does not work#

The index says to set the key

RANKLI_BLOG_API_KEY is missing where the build runs. Vercel and Netlify need it in the project settings as well as in your local file.

The index is empty

No articles have been published to this integration yet. An article publishes to the connections attached to its product; check the product’s integrations list in Rankli.

Changes do not appear

The revalidation window has not passed. Wait for it, redeploy, or shorten RANKLI_BLOG_REVALIDATE.