Guides
Set up a new project
Walk through creating a Blocklify space, modeling content, and creating a read token. When you are ready to connect a site, pick a stack from the Stack dropdown (Next.js or React) and follow that guide.
1.Create a space
In Admin → Spaces, click Add New… and choose a template:
- Starter space — Page content type, Hero / Text / Image blocks, and a draft sample
homeentry. Fastest path to see live preview. - Clean space — Empty project. You add content types and blocks yourself (step 2).
Open the space card to enter the dashboard, then continue below.
2.Blocks and content types
If you used Starter, skip to step 3. For a clean space:
- Go to Blocks and create a content type (root) block — e.g. Page. This defines which nestable blocks an entry of that type may use.
- Create nestable blocks (Hero, Text, Image, etc.) with the custom fields your theme will render (headline, body, image, etc.). Each field name becomes a key on the block JSON your frontend receives.
- Optionally set the space’s default content type under Space settings.
For a full walkthrough of schemas, asset fields, and the starter Image block, see Building blocks.
3.Create an entry
Open Entries → create an entry (or use the starter home). Give it a slug — live preview loads your frontend with ?slug=…&preview=1, so the slug must match a page your site can resolve.
Add blocks in the entry editor. You can finish the remaining steps before the iframe lights up; the structure sketch shows your draft until then.
4.Create a read token
Go to Access tokens (or Space settings → Tokens). Create a read token scoped to this space. Copy the blocklify_… value — your frontend uses it to fetch entries.
Send it as Authorization: Bearer … or X-API-Key: …. Read tokens only deliver content; writes still require an admin session.
5.Connect your frontend
Choose your stack first
Use the Stack dropdown in the left sidebar, or open a guide:
Or install the SDK yourself in any React project:
bun add @blocklify/preview
# or: npm install @blocklify/preview
# Next.js: copy the starter preview and home page
cp -R node_modules/@blocklify/preview/starter/nextjs/app ./appPeer dependencies: react and react-dom (≥18). Then set env vars on your site:
BLOCKLIFY_API_URL=https://your-blocklify-host
BLOCKLIFY_ACCESS_TOKEN=blocklify_…import { createBlocklifyClient } from "@blocklify/preview";
const client = createBlocklifyClient({
baseUrl: process.env.BLOCKLIFY_API_URL!,
accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
});
const entry = await client.getEntry("home");
// entry.content.body → array of blocks with your custom fieldsUse published: true for production pages. Omit it (or use draft-aware routes) when you need unpublished content outside the live preview iframe. Full clean install: Next.js guide.
6.How live preview renders blocks
The entry editor embeds your site in an iframe and sends draft JSON via postMessage (blocklify-draft). BlocklifyPreview from the package:
- Reads the blocks array from the draft (default field
body). - Looks up each block’s
typein yourblockMapand renders that React component. - Passes
block(all custom field values) andBlocklifyEditable(click-to-focus props) into each component.
Mount a dedicated route (e.g. /preview):
// app/preview/page.tsx (Next.js App Router)
"use client";
import { BlocklifyPreview } from "@blocklify/preview";
import { Hero, Text, ImageBlock } from "@/components/blocks";
const blockMap = {
hero: Hero,
text: Text,
image: ImageBlock,
};
export default function PreviewPage() {
return <BlocklifyPreview blockMap={blockMap} blocksFieldName="body" />;
}The admin opens {previewBase}?slug={entrySlug}&preview=1. Your route can ignore those query params for the iframe draft path; use them if you also want a stand-alone preview that fetches by slug.
7.Enable live edit on theme blocks (custom fields)
Live edit is block-level: clicking a block in the iframe focuses that block in the entry editor so you can edit its custom fields (headline, text, image, …). The package gives you the props — your theme must spread them onto the DOM.
- Type the component with package props
Import
BlocklifyBlockPropsfrom@blocklify/preview. You receiveblock(field values) and optionalBlocklifyEditable(empty outside the iframe). - Spread editable props on the root element
Always spread
{...BlocklifyEditable}on the outermost element of the block. Outside preview this is a no-op ({}); inside the iframe it adds click handlers and editable borders. - Render custom fields from
blockField names in the Blocklify block schema map 1:1 to keys on
block(e.g. schema fieldheadline→block.headline). - Register the block in
blockMapThe key must match the block
typestring from Blocklify (e.g.hero). - Verify in the entry editor
Open live preview, click the block outline in the iframe — the matching block form (with your custom fields) should expand in the editor.
// components/blocks/Hero.tsx
import type { BlocklifyBlockProps } from "@blocklify/preview";
export function Hero({ block, BlocklifyEditable = {} }: BlocklifyBlockProps) {
const headline = typeof block.headline === "string" ? block.headline : "";
const subtext = typeof block.subtext === "string" ? block.subtext : "";
return (
<section className="hero" {...BlocklifyEditable}>
<h1>{headline}</h1>
{subtext ? <p>{subtext}</p> : null}
</section>
);
}Nested blocks (e.g. a Page or Grid that contains children): accept blockMap from props and render children with BlocklifyPreviewRenderer, or map over nested arrays and pass BlocklifyEditable through the same way. Every clickable region that should open the editor needs the spread on its root.
8.Register the Live preview URL
In the space, open Settings → Live preview URLs and add your frontend preview base, for example:
# Built-in demo (this app)
https://localhost:3000/preview
# Your own frontend
https://localhost:6969/previewThis Blocklify app ships a demo at /preview so you can test live preview without a separate site. Use your own theme URL in production.
Prefer space-level preview URLs. A global NEXT_PUBLIC_LIVE_PREVIEW_URL on the Blocklify server is only a fallback for local Blocklify development.
Troubleshooting
- Blank iframe — Confirm the preview URL is reachable from your browser, the entry has a slug, and the path matches your preview route (including trailing path segments).
- Structure sketch only — No preview URL is set for this space yet. Complete steps 6–8.
- API 401 — Missing or wrong token header; ensure the read token is scoped to the correct space.
- Drafts not updating — The preview page must use
BlocklifyPreview(oruseBlocklifyPreview) from@blocklify/previewinside the iframe. Cross-originpostMessagedoes not require CORS. - Click does nothing — Spread
{...BlocklifyEditable}on the block’s root element and include the component inblockMap. - Unknown block type — Add that type to your
blockMap; the preview shows a placeholder until you do. - Fields empty in theme — Confirm the schema field name matches the key you read on
block(case-sensitive).
API reference: OpenAPI docs. Package source: packages/preview.