Next.js guide
Clean Next.js install
Start from an empty Next.js App Router project, wire @blocklify/preview, and point Blocklify live preview at your new site.
Need a space and read token first? Getting started.
1.Prerequisites
- Node.js 24.x (or current LTS) and a package manager (
bun,npm, orpnpm). - Blocklify running locally (e.g.
https://localhost:3000) with a space, an entry that has a slug, and a read token. - Keep the frontend on a different port than Blocklify (this guide uses
3001).
2.Create the Next.js app
Create the app in its own folder:
# App Router, TypeScript, Tailwind (recommended defaults)
bunx create-next-app@latest my-blocklify-site
# or: npx create-next-app@latest my-blocklify-site
cd my-blocklify-siteWhen prompted, choose App Router, TypeScript, and Tailwind. You can skip ESLint/src-dir extras if you prefer defaults.
3.Install @blocklify/preview
Install the SDK from npm. The package ships compiled JavaScript that Next.js can import directly.
bun add @blocklify/preview
# or: npm install @blocklify/preview4.Environment variables
Create .env.local in the Next.js app:
# Blocklify CMS origin (no trailing slash)
BLOCKLIFY_API_URL=https://localhost:3000
# Same origin for the browser preview page (asset ids)
NEXT_PUBLIC_BLOCKLIFY_API_URL=https://localhost:3000
# Read token from Admin → Access tokens (blocklify_…)
BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_hereRestart the Next.js dev server after changing env files. Never commit the token to git.
5.Add theme block components
The package includes starter components for hero, text, image, and cta. Copy the preview and home pages from the package:
cp -R node_modules/@blocklify/preview/starter/nextjs/app ./app
cp node_modules/@blocklify/preview/starter/nextjs/.env.example ./.env.localOr build the map yourself. Pass the Blocklify origin so asset ids can load:
import { createStarterBlockMap } from "@blocklify/preview";
export const blockMap = createStarterBlockMap({
assetBaseUrl: process.env.NEXT_PUBLIC_BLOCKLIFY_API_URL,
});6.Add the /preview route
This page is what the Blocklify entry editor loads in its iframe:
// app/preview/page.tsx
"use client";
import { BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
const blockMap = createStarterBlockMap({
assetBaseUrl: process.env.NEXT_PUBLIC_BLOCKLIFY_API_URL,
});
export default function PreviewPage() {
return (
<BlocklifyPreview
blockMap={blockMap}
blocksFieldName="body"
emptyMessage="Waiting for content from the Blocklify editor…"
/>
);
}7.Optional: published page via the API
For the public site (outside the iframe), fetch with the client:
// app/page.tsx
import {
BlocklifyEntryView,
createBlocklifyClient,
createStarterBlockMap,
} from "@blocklify/preview";
const blockMap = createStarterBlockMap({
assetBaseUrl: process.env.BLOCKLIFY_API_URL,
});
const client = createBlocklifyClient({
baseUrl: process.env.BLOCKLIFY_API_URL!,
accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
});
export default async function HomePage() {
const entry = await client.getEntry("home");
return (
<main>
<BlocklifyEntryView blocks={entry?.content.body} blockMap={blockMap} />
</main>
);
}Use getEntries({ published: true }) when you only want published content in production.
8.Register the Live preview URL
- In Blocklify, open the space → Settings → Live preview URLs.
- Add a named URL, for example:
Usehttp://localhost:3001/previewhttps://if your Next.js app also runs with HTTPS. - Open an entry with a slug and confirm the right-hand panel loads your Next.js preview. Click a block outline to focus its fields in the editor.
Quick alternative while developing Blocklify itself: point preview at this app’s built-in demo https://localhost:3000/preview — but your own Next.js site is what you want for a real theme.
9.Run both apps
# Terminal A — Blocklify CMS
cd ../blocklify
bun run dev
# → https://localhost:3000
# Terminal B — your Next.js site
cd ../my-blocklify-site
bun run dev -- --port 3001
# → http://localhost:3001If the iframe is blank, check the preview URL, that the entry has a slug, and that browser privacy settings are not blocking localhost iframes. More tips in Getting started → Troubleshooting.