@blocklify/preview 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Blocklify
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,74 @@
-# Temporary Holding Version
+# @blocklify/preview
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Frontend SDK for [Blocklify](https://www.blocklify.app): Content API client, live preview, and starter blocks for a new website.
+
+## Install
+
+```bash
+bun add @blocklify/preview
+# or: npm install @blocklify/preview
+```
+
+Peer dependencies: `react` and `react-dom` (≥18).
+
+## New Next.js site
+
+```bash
+bunx create-next-app@latest my-blocklify-site
+cd my-blocklify-site
+bun add @blocklify/preview
+cp -R node_modules/@blocklify/preview/starter/nextjs/app ./app
+cp node_modules/@blocklify/preview/starter/nextjs/.env.example ./.env.local
+```
+
+Fill in `.env.local`:
+
+```bash
+BLOCKLIFY_API_URL=https://localhost:3000
+NEXT_PUBLIC_BLOCKLIFY_API_URL=https://localhost:3000
+BLOCKLIFY_ACCESS_TOKEN=blocklify_…
+```
+
+Run the site on port 3001 and register `http://localhost:3001/preview` under Space → Settings → Live preview URLs.
+
+`app/page.tsx` renders the published `home` entry. `app/preview/page.tsx` is the editor iframe.
+
+## New React (Vite) site
+
+```bash
+bunx create-vite@latest my-blocklify-site --template react-ts
+cd my-blocklify-site
+bun add @blocklify/preview react-router-dom
+cp node_modules/@blocklify/preview/starter/react/src/App.tsx ./src/App.tsx
+cp node_modules/@blocklify/preview/starter/react/src/main.tsx ./src/main.tsx
+mkdir -p src/pages
+cp node_modules/@blocklify/preview/starter/react/src/pages/PreviewPage.tsx ./src/pages/PreviewPage.tsx
+cp node_modules/@blocklify/preview/starter/react/.env.example ./.env
+```
+
+Register `http://localhost:5173/preview` as the live preview URL.
+
+## What the starter renders
+
+Matches a Blocklify starter space:
+
+| Block type | Fields                                                     |
+| ---------- | ---------------------------------------------------------- |
+| `hero`     | `headline`, `subheadline`, `image`, `cta_text`, `cta_link` |
+| `text`     | `content` (HTML)                                           |
+| `image`    | `image`, `caption`, `alt`                                  |
+| `cta`      | `headline`, `subtext`, `button_text`, `button_link`        |
+
+`hero_block`, `text_block`, and `image_block` use the same components.
+
+Asset fields can be an id, a URL, or `{ url }`. Pass the Blocklify origin so ids load from `/api/assets/{id}/file`:
+
+```ts
+import { BlocklifyEntryView, BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: process.env.BLOCKLIFY_API_URL,
+});
+```
+
+Use `blockMap` with `BlocklifyPreview` on `/preview`, and `BlocklifyEntryView` for the public page.

package/dist/client.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Lightweight client for the Blocklify Content API.
+ * Use from your website or app to fetch entries and components with an access token.
+ *
+ * @example
+ * const client = createBlocklifyClient({
+ *   baseUrl: process.env.BLOCKLIFY_API_URL!,
+ *   accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
+ * });
+ * const entries = await client.getEntries({ published: true });
+ * const home = await client.getEntry("home");
+ */
+export type BlocklifyClientConfig = {
+    /** Blocklify app base URL (e.g. https://your-blocklify-app.com, no trailing slash) */
+    baseUrl: string;
+    /** Access token (from Admin → Access tokens). Prefix: blocklify_... */
+    accessToken: string;
+};
+export type BlocklifyEntry = {
+    id: string;
+    spaceId: string;
+    slug: string;
+    name: string;
+    content: Record<string, unknown> & {
+        body?: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        blocks?: Array<{
+            type: string;
+            [k: string]: unknown;
+        }>;
+        title?: string;
+    };
+    isPublished: boolean;
+    publishedAt: string | null;
+    contentType: {
+        id: string;
+        type: string;
+        name?: string;
+        schema?: string;
+    };
+    createdAt: string;
+    updatedAt: string;
+};
+export type BlocklifyComponent = {
+    id: string;
+    spaceId: string;
+    name: string;
+    type: string;
+    schema: {
+        fields?: Array<{
+            name: string;
+            type: string;
+            [k: string]: unknown;
+        }>;
+    };
+    isRoot: boolean;
+    isNestable: boolean;
+};
+export type BlocklifySiteAsset = {
+    id: string;
+    url: string;
+    filename: string;
+    mimeType: string;
+    alt: string | null;
+};
+export type BlocklifySiteSettings = {
+    defaultPageTitle: string | null;
+    favicon: BlocklifySiteAsset | null;
+    logo: BlocklifySiteAsset | null;
+    custom: Array<{
+        key: string;
+        value: string;
+    }>;
+};
+export declare function createBlocklifyClient(config: BlocklifyClientConfig): {
+    /** List entries. Use published: true for production; omit for preview (drafts + published). */
+    getEntries(options?: {
+        published?: boolean;
+        spaceId?: string;
+    }): Promise<BlocklifyEntry[]>;
+    /** Get one entry by slug. Use for live preview. Returns null when entry is not found (404). */
+    getEntry(slug: string, options?: {
+        spaceId?: string;
+    }): Promise<BlocklifyEntry | null>;
+    /** List components (block definitions) for the space. */
+    getComponents(options?: {
+        spaceId?: string;
+    }): Promise<BlocklifyComponent[]>;
+    /** Site settings (default title, favicon, logo, custom key–value pairs). */
+    getSiteSettings(options?: {
+        spaceId?: string;
+    }): Promise<BlocklifySiteSettings>;
+};

package/dist/client.js

@@ -0,0 +1,83 @@
+/**
+ * Lightweight client for the Blocklify Content API.
+ * Use from your website or app to fetch entries and components with an access token.
+ *
+ * @example
+ * const client = createBlocklifyClient({
+ *   baseUrl: process.env.BLOCKLIFY_API_URL!,
+ *   accessToken: process.env.BLOCKLIFY_ACCESS_TOKEN!,
+ * });
+ * const entries = await client.getEntries({ published: true });
+ * const home = await client.getEntry("home");
+ */
+function buildHeaders(accessToken) {
+    return {
+        Authorization: `Bearer ${accessToken}`,
+        "Content-Type": "application/json",
+    };
+}
+function ensureNoTrailingSlash(url) {
+    return url.replace(/\/+$/, "");
+}
+export function createBlocklifyClient(config) {
+    const baseUrl = ensureNoTrailingSlash(config.baseUrl);
+    const headers = buildHeaders(config.accessToken);
+    async function request(path, options) {
+        const url = new URL(path.startsWith("http") ? path : baseUrl + path);
+        if (options?.searchParams) {
+            Object.entries(options.searchParams).forEach(([k, v]) => url.searchParams.set(k, v));
+        }
+        const res = await fetch(url.toString(), {
+            method: options?.method ?? "GET",
+            headers,
+            cache: "no-store",
+        });
+        if (!res.ok) {
+            const err = (await res.json().catch(() => ({})));
+            throw new Error(err.error ?? `API error ${res.status}`);
+        }
+        return res.json();
+    }
+    return {
+        /** List entries. Use published: true for production; omit for preview (drafts + published). */
+        getEntries(options) {
+            const searchParams = {};
+            if (options?.published === true)
+                searchParams.published = "true";
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/entries", { searchParams });
+        },
+        /** Get one entry by slug. Use for live preview. Returns null when entry is not found (404). */
+        async getEntry(slug, options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            const query = new URLSearchParams(searchParams).toString();
+            const path = `/api/entries/${encodeURIComponent(slug)}${query ? `?${query}` : ""}`;
+            const url = new URL(path.startsWith("http") ? path : baseUrl + path);
+            const res = await fetch(url.toString(), { method: "GET", headers, cache: "no-store" });
+            if (res.status === 404)
+                return null;
+            if (!res.ok) {
+                const err = (await res.json().catch(() => ({})));
+                throw new Error(err.error ?? `API error ${res.status}`);
+            }
+            return res.json();
+        },
+        /** List components (block definitions) for the space. */
+        getComponents(options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/components", { searchParams });
+        },
+        /** Site settings (default title, favicon, logo, custom key–value pairs). */
+        getSiteSettings(options) {
+            const searchParams = {};
+            if (options?.spaceId)
+                searchParams.space = options.spaceId;
+            return request("/api/site-settings", { searchParams });
+        },
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * @blocklify/preview — install in your frontend / theme to fetch content and enable live preview.
+ *
+ * @example
+ * import {
+ *   BlocklifyPreview,
+ *   createBlocklifyClient,
+ *   type BlocklifyBlockProps,
+ * } from "@blocklify/preview";
+ */
+export { createBlocklifyClient, type BlocklifyClientConfig, type BlocklifyComponent, type BlocklifyEntry, type BlocklifySiteAsset, type BlocklifySiteSettings, } from "./client.js";
+export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, type BlocklifyBlock, type BlocklifyBlockProps, type BlocklifyPreviewProps, type BlockMap, type DataBlokCPayload, } from "./preview.js";
+export { default } from "./preview.js";
+export { BlocklifyEntryView, blocklifyAssetUrl, createStarterBlockMap, starterBlockMap, type StarterBlockMapOptions, } from "./starter.js";

package/dist/index.js

@@ -0,0 +1,14 @@
+/**
+ * @blocklify/preview — install in your frontend / theme to fetch content and enable live preview.
+ *
+ * @example
+ * import {
+ *   BlocklifyPreview,
+ *   createBlocklifyClient,
+ *   type BlocklifyBlockProps,
+ * } from "@blocklify/preview";
+ */
+export { createBlocklifyClient, } from "./client.js";
+export { BlocklifyEditable, BlocklifyPreview, BlocklifyPreviewRenderer, BLOCKLIFY_PEER_FOCUS, BLOCKLIFY_PREVIEW_STYLES, BLOCKLIFY_SCROLL_TO_BLOCK, getDataBlokC, PREVIEW_EDITABLE_CSS, useBlocklifyPreview, } from "./preview.js";
+export { default } from "./preview.js";
+export { BlocklifyEntryView, blocklifyAssetUrl, createStarterBlockMap, starterBlockMap, } from "./starter.js";

package/dist/preview.d.ts

@@ -0,0 +1,111 @@
+import React from "react";
+/**
+ * Blocklify live-preview connector. Editable wrapper styles (border, hover) are defined here (PREVIEW_EDITABLE_CSS)
+ * and sent from the admin to the iframe via postMessage (blocklify-preview-styles). The other app only needs
+ * to use this lib and listen for that message; it will receive and inject the same styles so no duplication.
+ */
+/** Block shape sent by Blocklify (draft content or API). Your block components receive this. */
+export type BlocklifyBlock = {
+    type: string;
+    _uid?: string;
+    [k: string]: unknown;
+};
+/** Props passed to block components: block, optional BlocklifyEditable (spread on root in iframe), optional blockMap (for nested blocks). */
+export type BlocklifyBlockProps = {
+    block: BlocklifyBlock;
+    BlocklifyEditable?: Record<string, unknown>;
+    blockMap?: BlockMap;
+};
+/** Map block type string → component that receives { block, BlocklifyEditable? }. Spread BlocklifyEditable on the root element for click-to-focus in the preview iframe. */
+export type BlockMap = Record<string, React.ComponentType<BlocklifyBlockProps>>;
+/** Storyblok-style payload for data-blok-c (JSON string). */
+export type DataBlokCPayload = {
+    name: string;
+    uid: string;
+    space?: string;
+    id?: string;
+};
+/**
+ * Builds the value for the data-blok-c attribute (Storyblok-style JSON string).
+ * Use when you need to set data-blok-c yourself; otherwise BlocklifyEditable includes it.
+ */
+export declare function getDataBlokC(block: BlocklifyBlock, options?: {
+    spaceId?: string;
+    blockId?: string;
+}): string;
+/**
+ * Returns props to spread on the root element of a block so it becomes clickable in the preview iframe (like Storyblok’s storyblokEditable).
+ * Sets data-blok-c (Storyblok-style JSON: name, uid, space?, id?) and data-blok-uid for compatibility.
+ * Only returns non-empty when in iframe with onBlockClick; otherwise returns {} so components work unchanged outside preview.
+ * Use in the preview renderer; components just spread the BlocklifyEditable prop they receive.
+ * Clicks send the block's _uid so the editor can open the form for the correct block.
+ */
+export declare function BlocklifyEditable(block: BlocklifyBlock, index: number, onBlockClick: ((uid: string) => void) | undefined, options?: {
+    spaceId?: string;
+    blockId?: string;
+}): Record<string, unknown>;
+/** Message type the admin sends to the iframe with editable wrapper CSS (single source of truth in Blocklify). */
+export declare const BLOCKLIFY_PREVIEW_STYLES = "blocklify-preview-styles";
+/** Message type the admin sends when peer-focused blocks change, so the preview can render colored borders. */
+export declare const BLOCKLIFY_PEER_FOCUS = "blocklify-peer-focus";
+/** Message type the admin sends to scroll a block into view in the preview iframe (e.g. when focusing a field in the editor). */
+export declare const BLOCKLIFY_SCROLL_TO_BLOCK = "blocklify-scroll-to-block";
+/** Single source of truth for editable block styling in the preview iframe. Sent by the admin via postMessage so the other app doesn’t need to duplicate it. */
+export declare const PREVIEW_EDITABLE_CSS = "\n:root {\n    --radius: 0.5rem;\n}\n[data-blocklify-iframe-editable],\n[data-blok-uid] {\n    cursor: pointer !important;\n    border: 2px solid #2563eb !important;\n    border-radius: var(--radius) !important;\n    padding: 6px !important;\n    margin-bottom: 10px !important;\n    box-sizing: border-box !important;\n    transition: border-color 0.2s ease, background-color 0.2s ease !important;\n    position: relative !important;\n    min-height: 24px !important;\n}\n[data-blocklify-iframe-editable]:hover,\n[data-blok-uid]:hover {\n    border-color: #1d4ed8 !important;\n    background-color: rgba(37, 99, 235, 0.06) !important;\n}\n@keyframes blocklify-preview-focus-blink {\n    0% {\n        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);\n        border-color: #2563eb !important;\n    }\n    35% {\n        box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.45);\n        border-color: #1d4ed8 !important;\n    }\n    100% {\n        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);\n        border-color: #2563eb !important;\n    }\n}\n.blocklify-preview-focus-blink {\n    animation: blocklify-preview-focus-blink 0.55s ease-out 1 !important;\n}\n@media (prefers-reduced-motion: reduce) {\n    .blocklify-preview-focus-blink {\n        animation: none !important;\n    }\n}\n";
+/**
+ * Hook that connects your preview page to the Blocklify admin iframe:
+ * - Listens for draft content via postMessage (type: "blocklify-draft").
+ * - Sends block clicks back to the editor (type: "blocklify-block-click").
+ * Use this when your preview page is loaded inside the Blocklify admin iframe.
+ */
+export declare function useBlocklifyPreview(blocksFieldName?: string): {
+    blocks: BlocklifyBlock[];
+    isInIframe: boolean;
+    onBlockClick: (uid: string) => void;
+    showEmptyMessage: boolean;
+    /** Space id from the draft message (for data-blok-c when admin sends spaceId). */
+    spaceId: string | null;
+    /** Use this when rendering editable wrappers: parent-sent CSS or PREVIEW_EDITABLE_CSS. */
+    editableCss: string;
+    /** Peer-focused blocks: uid → { name, color }. Inject as colored borders to show who is editing what. */
+    peerFocusedBlocks: Record<string, {
+        name: string;
+        color: string;
+    }>;
+};
+type BlocklifyPreviewRendererProps = {
+    blocks: BlocklifyBlock[];
+    blockMap: BlockMap;
+    onBlockClick?: (uid: string) => void;
+    /** Space id for data-blok-c (Storyblok-style). Pass from useBlocklifyPreview().spaceId when admin sends it. */
+    spaceId?: string | null;
+    /** CSS for editable wrappers. When in iframe, pass editableCss from useBlocklifyPreview (from parent or default). */
+    editableCss?: string;
+    /** Optional: pass to each component so nested blocks (e.g. Page, Grid) can render. */
+    blockMapForNested?: BlockMap;
+};
+/**
+ * Renders blocks using your blockMap. Passes BlocklifyEditable (from BlocklifyEditable()) so components can spread it on their root for click-to-focus in the iframe.
+ * Styles are injected from editableCss (sent by admin via postMessage). No wrapper div – components apply {...BlocklifyEditable} themselves.
+ */
+export declare function BlocklifyPreviewRenderer({ blocks, blockMap, onBlockClick, spaceId, editableCss, blockMapForNested, }: BlocklifyPreviewRendererProps): import("react/jsx-runtime").JSX.Element;
+export type BlocklifyPreviewProps = {
+    /** Map of block type → component that receives { block }. Define your blocks in your app and pass this. */
+    blockMap: BlockMap;
+    /** Key in draft content that holds the blocks array (default "body"). */
+    blocksFieldName?: string;
+    /** Message shown when the preview iframe has not received draft content yet. */
+    emptyMessage?: string;
+    /** Optional className for the root wrapper. */
+    className?: string;
+};
+/**
+ * Preview connector for Blocklify. Use this on your frontend’s preview page (e.g. /preview).
+ * You only need to define your block components and a blockMap; this component handles:
+ * - Receiving draft content from the Blocklify admin via postMessage
+ * - Sending block clicks back to the editor
+ * - Empty state message and editable borders when embedded in the admin iframe
+ */
+export declare function BlocklifyPreview({ blockMap, blocksFieldName, emptyMessage, className, }: BlocklifyPreviewProps): import("react/jsx-runtime").JSX.Element;
+/** Default export so both "import BlocklifyPreview from '...'" and "import { BlocklifyPreview } from '...'" work. */
+export default BlocklifyPreview;

package/dist/preview.js

@@ -0,0 +1,256 @@
+"use client";
+import { jsxs as _jsxs, jsx as _jsx, Fragment as _Fragment } from "react/jsx-runtime";
+import { useCallback, useEffect, useState, useSyncExternalStore } from "react";
+/**
+ * Builds the value for the data-blok-c attribute (Storyblok-style JSON string).
+ * Use when you need to set data-blok-c yourself; otherwise BlocklifyEditable includes it.
+ */
+export function getDataBlokC(block, options) {
+    const payload = {
+        name: block.type,
+        uid: block._uid ?? "",
+        ...(options?.spaceId != null && options.spaceId !== "" && { space: options.spaceId }),
+        ...((options?.blockId ?? block.id) != null &&
+            (options?.blockId ?? block.id) !== "" && {
+            id: String(options?.blockId ?? block.id),
+        }),
+    };
+    return JSON.stringify(payload);
+}
+/**
+ * Returns props to spread on the root element of a block so it becomes clickable in the preview iframe (like Storyblok’s storyblokEditable).
+ * Sets data-blok-c (Storyblok-style JSON: name, uid, space?, id?) and data-blok-uid for compatibility.
+ * Only returns non-empty when in iframe with onBlockClick; otherwise returns {} so components work unchanged outside preview.
+ * Use in the preview renderer; components just spread the BlocklifyEditable prop they receive.
+ * Clicks send the block's _uid so the editor can open the form for the correct block.
+ */
+export function BlocklifyEditable(block, index, onBlockClick, options) {
+    if (!onBlockClick)
+        return {};
+    const uid = block._uid ?? "";
+    return {
+        "data-blocklify-iframe-editable": true,
+        "data-blok-c": getDataBlokC(block, options),
+        ...(uid && { "data-blok-uid": uid }),
+        role: "button",
+        tabIndex: 0,
+        title: "Click to focus in editor",
+        "aria-label": `Edit block ${index + 1}, ${block.type}`,
+        onClick: (e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            onBlockClick(uid);
+        },
+        onKeyDown: (e) => {
+            if (e.key === "Enter" || e.key === " ") {
+                e.preventDefault();
+                onBlockClick(uid);
+            }
+        },
+    };
+}
+const BLOCKLIFY_DRAFT = "blocklify-draft";
+const BLOCKLIFY_BLOCK_CLICK = "blocklify-block-click";
+/** Message type the admin sends to the iframe with editable wrapper CSS (single source of truth in Blocklify). */
+export const BLOCKLIFY_PREVIEW_STYLES = "blocklify-preview-styles";
+/** Message type the admin sends when peer-focused blocks change, so the preview can render colored borders. */
+export const BLOCKLIFY_PEER_FOCUS = "blocklify-peer-focus";
+/** Message type the admin sends to scroll a block into view in the preview iframe (e.g. when focusing a field in the editor). */
+export const BLOCKLIFY_SCROLL_TO_BLOCK = "blocklify-scroll-to-block";
+const PREVIEW_FOCUS_BLINK_CLASS = "blocklify-preview-focus-blink";
+const PREVIEW_FOCUS_BLINK_MS = 550;
+function pulsePreviewBlock(el) {
+    el.classList.remove(PREVIEW_FOCUS_BLINK_CLASS);
+    void el.offsetWidth;
+    el.classList.add(PREVIEW_FOCUS_BLINK_CLASS);
+    window.setTimeout(() => {
+        el.classList.remove(PREVIEW_FOCUS_BLINK_CLASS);
+    }, PREVIEW_FOCUS_BLINK_MS);
+}
+function scrollPreviewBlockIntoView(uid) {
+    if (typeof document === "undefined" || !uid)
+        return;
+    const escaped = typeof CSS !== "undefined" && typeof CSS.escape === "function" ? CSS.escape(uid) : uid;
+    const el = document.querySelector(`[data-blok-uid="${escaped}"]`) ??
+        document.querySelector(`[data-blocklify-uid="${escaped}"]`);
+    if (!(el instanceof HTMLElement))
+        return;
+    el.scrollIntoView({ behavior: "smooth", block: "center", inline: "nearest" });
+    pulsePreviewBlock(el);
+}
+/** Single source of truth for editable block styling in the preview iframe. Sent by the admin via postMessage so the other app doesn’t need to duplicate it. */
+export const PREVIEW_EDITABLE_CSS = `
+:root {
+    --radius: 0.5rem;
+}
+[data-blocklify-iframe-editable],
+[data-blok-uid] {
+    cursor: pointer !important;
+    border: 2px solid #2563eb !important;
+    border-radius: var(--radius) !important;
+    padding: 6px !important;
+    margin-bottom: 10px !important;
+    box-sizing: border-box !important;
+    transition: border-color 0.2s ease, background-color 0.2s ease !important;
+    position: relative !important;
+    min-height: 24px !important;
+}
+[data-blocklify-iframe-editable]:hover,
+[data-blok-uid]:hover {
+    border-color: #1d4ed8 !important;
+    background-color: rgba(37, 99, 235, 0.06) !important;
+}
+@keyframes blocklify-preview-focus-blink {
+    0% {
+        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);
+        border-color: #2563eb !important;
+    }
+    35% {
+        box-shadow: 0 0 0 4px rgba(37, 99, 235, 0.45);
+        border-color: #1d4ed8 !important;
+    }
+    100% {
+        box-shadow: 0 0 0 0 rgba(37, 99, 235, 0);
+        border-color: #2563eb !important;
+    }
+}
+.${PREVIEW_FOCUS_BLINK_CLASS} {
+    animation: blocklify-preview-focus-blink 0.55s ease-out 1 !important;
+}
+@media (prefers-reduced-motion: reduce) {
+    .${PREVIEW_FOCUS_BLINK_CLASS} {
+        animation: none !important;
+    }
+}
+`;
+function subscribeIsInIframe() {
+    // iframe embedding does not change for the lifetime of the page.
+    return () => { };
+}
+function getIsInIframeSnapshot() {
+    return window.self !== window.top;
+}
+function getIsInIframeServerSnapshot() {
+    return false;
+}
+/**
+ * Hook that connects your preview page to the Blocklify admin iframe:
+ * - Listens for draft content via postMessage (type: "blocklify-draft").
+ * - Sends block clicks back to the editor (type: "blocklify-block-click").
+ * Use this when your preview page is loaded inside the Blocklify admin iframe.
+ */
+export function useBlocklifyPreview(blocksFieldName = "body") {
+    const [draftContent, setDraftContent] = useState(null);
+    /** CSS for editable wrappers: from parent (postMessage) or fallback to PREVIEW_EDITABLE_CSS. */
+    const [receivedEditableCss, setReceivedEditableCss] = useState(null);
+    const [peerFocusedBlocks, setPeerFocusedBlocks] = useState({});
+    const isInIframe = useSyncExternalStore(subscribeIsInIframe, getIsInIframeSnapshot, getIsInIframeServerSnapshot);
+    const [spaceId, setSpaceId] = useState(null);
+    useEffect(() => {
+        if (!isInIframe)
+            return;
+        const onMessage = (event) => {
+            if (event.data?.type === BLOCKLIFY_DRAFT && event.data.content != null) {
+                setDraftContent(event.data.content);
+                setSpaceId(typeof event.data.spaceId === "string" && event.data.spaceId.trim() !== ""
+                    ? event.data.spaceId
+                    : null);
+            }
+            if (event.data?.type === BLOCKLIFY_PREVIEW_STYLES &&
+                typeof event.data.css === "string") {
+                setReceivedEditableCss(event.data.css);
+            }
+            if (event.data?.type === BLOCKLIFY_PEER_FOCUS && event.data.peers != null) {
+                setPeerFocusedBlocks(event.data.peers);
+            }
+            if (event.data?.type === BLOCKLIFY_SCROLL_TO_BLOCK &&
+                typeof event.data.uid === "string" &&
+                event.data.uid.trim() !== "") {
+                // Wait a frame so draft content / DOM from a concurrent update can settle.
+                requestAnimationFrame(() => {
+                    scrollPreviewBlockIntoView(event.data.uid);
+                });
+            }
+        };
+        window.addEventListener("message", onMessage);
+        return () => window.removeEventListener("message", onMessage);
+    }, [isInIframe]);
+    const onBlockClick = useCallback((uid) => {
+        if (typeof window === "undefined" || window === window.parent)
+            return;
+        window.parent.postMessage({ type: BLOCKLIFY_BLOCK_CLICK, uid, blocksFieldName }, "*");
+    }, [blocksFieldName]);
+    const rawBlocks = draftContent?.[blocksFieldName];
+    const blocks = Array.isArray(rawBlocks)
+        ? rawBlocks.filter((b) => b != null &&
+            typeof b === "object" &&
+            typeof b.type === "string")
+        : [];
+    const showEmptyMessage = isInIframe && blocks.length === 0 && draftContent === null;
+    return {
+        blocks,
+        isInIframe,
+        onBlockClick,
+        showEmptyMessage,
+        /** Space id from the draft message (for data-blok-c when admin sends spaceId). */
+        spaceId,
+        /** Use this when rendering editable wrappers: parent-sent CSS or PREVIEW_EDITABLE_CSS. */
+        editableCss: receivedEditableCss ?? PREVIEW_EDITABLE_CSS,
+        /** Peer-focused blocks: uid → { name, color }. Inject as colored borders to show who is editing what. */
+        peerFocusedBlocks,
+    };
+}
+/** Fallback when a block type has no component in the blockMap – never pass undefined to React. */
+function UnknownBlockFallback({ block, BlocklifyEditable = {}, }) {
+    return (_jsxs("section", { style: {
+            padding: "1rem 1.25rem",
+            opacity: 0.9,
+            border: "2px dashed #94a3b8",
+            borderRadius: 8,
+            backgroundColor: "rgba(148, 163, 184, 0.08)",
+            color: "#64748b",
+            fontSize: "0.875rem",
+        }, ...BlocklifyEditable, children: [_jsxs("strong", { style: { color: "#475569" }, children: ["Block type \"", block.type, "\" not found."] }), _jsx("p", { style: { margin: "0.5rem 0 0", lineHeight: 1.5 }, children: "Add a component for this block type to your project's blockMap (e.g. in your preview page) to render it here." })] }));
+}
+/**
+ * Renders blocks using your blockMap. Passes BlocklifyEditable (from BlocklifyEditable()) so components can spread it on their root for click-to-focus in the iframe.
+ * Styles are injected from editableCss (sent by admin via postMessage). No wrapper div – components apply {...BlocklifyEditable} themselves.
+ */
+export function BlocklifyPreviewRenderer({ blocks, blockMap, onBlockClick, spaceId, editableCss = PREVIEW_EDITABLE_CSS, blockMapForNested, }) {
+    const safeBlockMap = blockMap ?? {};
+    const nestedMap = blockMapForNested ?? safeBlockMap;
+    const resolveComponent = (type) => safeBlockMap[type] ??
+        (type.endsWith("_block") ? safeBlockMap[type.slice(0, -6)] : undefined) ??
+        UnknownBlockFallback;
+    return (_jsxs(_Fragment, { children: [_jsx("style", { id: "blocklify-preview-editable-styles", dangerouslySetInnerHTML: { __html: editableCss } }), blocks.map((block, i) => {
+                const Component = resolveComponent(block.type);
+                const key = block._uid ?? i;
+                const blocklifyEditable = BlocklifyEditable(block, i, onBlockClick, {
+                    spaceId: spaceId ?? undefined,
+                    blockId: block.id,
+                });
+                return (_jsx(Component, { block: block, BlocklifyEditable: blocklifyEditable, ...(nestedMap && { blockMap: nestedMap }) }, key));
+            })] }));
+}
+/**
+ * Preview connector for Blocklify. Use this on your frontend’s preview page (e.g. /preview).
+ * You only need to define your block components and a blockMap; this component handles:
+ * - Receiving draft content from the Blocklify admin via postMessage
+ * - Sending block clicks back to the editor
+ * - Empty state message and editable borders when embedded in the admin iframe
+ */
+export function BlocklifyPreview({ blockMap, blocksFieldName = "body", emptyMessage = "Waiting for content from editor…", className, }) {
+    const { blocks, isInIframe, onBlockClick, showEmptyMessage, spaceId, editableCss, peerFocusedBlocks } = useBlocklifyPreview(blocksFieldName);
+    const peerFocusCss = Object.entries(peerFocusedBlocks)
+        .map(([uid, { color }]) => `[data-blok-uid="${uid}"] { border-color: ${color} !important; box-shadow: 0 0 0 2px ${color} !important; }`)
+        .join("\n");
+    return (_jsxs("div", { className: className ?? "min-h-screen bg-surface text-text blocklify-preview-non-interactive", children: [_jsx("style", { children: `
+                .blocklify-preview-non-interactive a,
+                .blocklify-preview-non-interactive button {
+                    pointer-events: none;
+                    cursor: default;
+                }
+            ` }), peerFocusCss && (_jsx("style", { id: "blocklify-peer-focus-styles", children: peerFocusCss })), showEmptyMessage && (_jsx("div", { className: "flex min-h-screen items-center justify-center", children: _jsx("p", { className: "text-sm text-text-muted", children: emptyMessage }) })), _jsx(BlocklifyPreviewRenderer, { blocks: blocks, blockMap: blockMap, onBlockClick: isInIframe ? onBlockClick : undefined, spaceId: spaceId, editableCss: editableCss, blockMapForNested: blockMap })] }));
+}
+/** Default export so both "import BlocklifyPreview from '...'" and "import { BlocklifyPreview } from '...'" work. */
+export default BlocklifyPreview;

package/dist/starter.d.ts

@@ -0,0 +1,22 @@
+import type { BlocklifyBlock, BlockMap } from "./preview.js";
+export type StarterBlockMapOptions = {
+    /**
+     * Blocklify origin, no trailing slash.
+     * Used when an asset field is still an id (`/api/assets/{id}/file` is public).
+     */
+    assetBaseUrl?: string;
+};
+/** URL for an asset field: expanded `{ url }`, an absolute/path string, or a bare asset id. */
+export declare function blocklifyAssetUrl(value: unknown, assetBaseUrl?: string): string | null;
+/**
+ * Theme components for a starter Blocklify space: hero, text, image, and cta.
+ * Also registers the `*_block` aliases.
+ */
+export declare function createStarterBlockMap(options?: StarterBlockMapOptions): BlockMap;
+/** Starter map without an asset origin. Expanded `{ url }` fields still render. */
+export declare const starterBlockMap: BlockMap;
+/** Renders an entry body with a block map. Use on the public site, outside the preview iframe. */
+export declare function BlocklifyEntryView({ blocks, blockMap, }: {
+    blocks?: BlocklifyBlock[] | null;
+    blockMap?: BlockMap;
+}): import("react/jsx-runtime").JSX.Element | null;

package/dist/starter.js

@@ -0,0 +1,139 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+function textOf(block, key) {
+    const value = block[key];
+    return typeof value === "string" ? value : "";
+}
+function absolutize(url, assetBaseUrl) {
+    if (/^https?:\/\//i.test(url) || url.startsWith("data:"))
+        return url;
+    if (url.startsWith("/") && assetBaseUrl) {
+        return `${assetBaseUrl.replace(/\/+$/, "")}${url}`;
+    }
+    return url;
+}
+/** URL for an asset field: expanded `{ url }`, an absolute/path string, or a bare asset id. */
+export function blocklifyAssetUrl(value, assetBaseUrl) {
+    if (value == null || value === "")
+        return null;
+    if (typeof value === "object") {
+        const record = value;
+        if (typeof record.url === "string" && record.url !== "") {
+            return absolutize(record.url, assetBaseUrl);
+        }
+        if (typeof record.id === "string" && record.id !== "") {
+            return blocklifyAssetUrl(record.id, assetBaseUrl);
+        }
+        return null;
+    }
+    if (typeof value !== "string")
+        return null;
+    if (/^https?:\/\//i.test(value) || value.startsWith("/") || value.startsWith("data:")) {
+        return absolutize(value, assetBaseUrl);
+    }
+    if (!assetBaseUrl)
+        return null;
+    return `${assetBaseUrl.replace(/\/+$/, "")}/api/assets/${encodeURIComponent(value)}/file`;
+}
+const sectionStyle = {
+    padding: "4rem 1.5rem",
+    maxWidth: "42rem",
+    margin: "0 auto",
+};
+function HeroBlock({ block, BlocklifyEditable = {}, assetBaseUrl, }) {
+    const headline = textOf(block, "headline");
+    const subheadline = textOf(block, "subheadline");
+    const ctaText = textOf(block, "cta_text");
+    const ctaLink = textOf(block, "cta_link") || "#";
+    const imageSrc = blocklifyAssetUrl(block.image, assetBaseUrl);
+    return (_jsxs("section", { style: { ...sectionStyle, textAlign: "center" }, ...BlocklifyEditable, children: [imageSrc ? (
+            // Themes install this package outside the Blocklify app, so they cannot use its Image component.
+            _jsx("img", { src: imageSrc, alt: textOf(block, "alt") || headline, style: { width: "100%", borderRadius: 12, marginBottom: "1.5rem" } })) : null, headline ? (_jsx("h1", { style: { fontSize: "2.5rem", lineHeight: 1.15, margin: 0 }, children: headline })) : null, subheadline ? (_jsx("p", { style: { marginTop: "1rem", fontSize: "1.125rem", opacity: 0.75 }, children: subheadline })) : null, ctaText ? (_jsx("a", { href: ctaLink, style: {
+                    display: "inline-block",
+                    marginTop: "1.5rem",
+                    padding: "0.75rem 1.5rem",
+                    borderRadius: 999,
+                    background: "#111",
+                    color: "#fff",
+                    textDecoration: "none",
+                    fontSize: "0.875rem",
+                }, children: ctaText })) : null] }));
+}
+function TextBlock({ block, BlocklifyEditable = {} }) {
+    const html = textOf(block, "content") || textOf(block, "text") || textOf(block, "html");
+    return (_jsx("section", { style: sectionStyle, ...BlocklifyEditable, children: html ? (_jsx("div", { dangerouslySetInnerHTML: { __html: html } })) : (_jsx("p", { style: { fontStyle: "italic", opacity: 0.6 }, children: "Empty text block" })) }));
+}
+function ImageBlock({ block, BlocklifyEditable = {}, assetBaseUrl, }) {
+    const src = blocklifyAssetUrl(block.image, assetBaseUrl);
+    const caption = textOf(block, "caption");
+    const alt = textOf(block, "alt") || caption;
+    return (_jsxs("figure", { style: { ...sectionStyle, paddingTop: "1.5rem", paddingBottom: "1.5rem" }, ...BlocklifyEditable, children: [src ? (_jsx("img", { src: src, alt: alt, style: { width: "100%", borderRadius: 12 } })) : (_jsx("div", { style: {
+                    padding: "3rem 1rem",
+                    textAlign: "center",
+                    border: "1px dashed #cbd5e1",
+                    borderRadius: 12,
+                    opacity: 0.7,
+                }, children: "No image selected" })), caption ? (_jsx("figcaption", { style: {
+                    marginTop: "0.5rem",
+                    textAlign: "center",
+                    fontSize: "0.875rem",
+                    opacity: 0.7,
+                }, children: caption })) : null] }));
+}
+function CtaBlock({ block, BlocklifyEditable = {} }) {
+    const headline = textOf(block, "headline");
+    const subtext = textOf(block, "subtext");
+    const buttonText = textOf(block, "button_text");
+    const buttonLink = textOf(block, "button_link") || "#";
+    return (_jsxs("section", { style: { ...sectionStyle, textAlign: "center" }, ...BlocklifyEditable, children: [headline ? _jsx("h2", { style: { fontSize: "1.75rem", margin: 0 }, children: headline }) : null, subtext ? _jsx("p", { style: { marginTop: "0.75rem", opacity: 0.75 }, children: subtext }) : null, buttonText ? (_jsx("a", { href: buttonLink, style: {
+                    display: "inline-block",
+                    marginTop: "1.5rem",
+                    padding: "0.75rem 1.5rem",
+                    borderRadius: 999,
+                    background: "#65a30d",
+                    color: "#fff",
+                    textDecoration: "none",
+                }, children: buttonText })) : null] }));
+}
+function withAssetBase(Component, assetBaseUrl) {
+    function StarterBlock(props) {
+        return _jsx(Component, { ...props, assetBaseUrl: assetBaseUrl });
+    }
+    StarterBlock.displayName = Component.displayName ?? Component.name;
+    return StarterBlock;
+}
+/**
+ * Theme components for a starter Blocklify space: hero, text, image, and cta.
+ * Also registers the `*_block` aliases.
+ */
+export function createStarterBlockMap(options) {
+    const assetBaseUrl = options?.assetBaseUrl;
+    const hero = withAssetBase(HeroBlock, assetBaseUrl);
+    const text = TextBlock;
+    const image = withAssetBase(ImageBlock, assetBaseUrl);
+    const cta = CtaBlock;
+    return {
+        hero,
+        hero_block: hero,
+        text,
+        text_block: text,
+        image,
+        image_block: image,
+        cta,
+    };
+}
+/** Starter map without an asset origin. Expanded `{ url }` fields still render. */
+export const starterBlockMap = createStarterBlockMap();
+function resolveBlock(blockMap, type) {
+    return blockMap[type] ?? (type.endsWith("_block") ? blockMap[type.slice(0, -6)] : undefined);
+}
+/** Renders an entry body with a block map. Use on the public site, outside the preview iframe. */
+export function BlocklifyEntryView({ blocks, blockMap = starterBlockMap, }) {
+    if (!blocks?.length)
+        return null;
+    return (_jsx(_Fragment, { children: blocks.map((block, index) => {
+            const Component = resolveBlock(blockMap, block.type);
+            if (!Component)
+                return null;
+            return (_jsx(Component, { block: block, blockMap: blockMap }, block._uid ?? `${block.type}-${index}`));
+        }) }));
+}

package/package.json

@@ -1,6 +1,68 @@
 {
-  "name": "@blocklify/preview",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+    "name": "@blocklify/preview",
+    "version": "0.2.0",
+    "description": "Blocklify frontend SDK: Content API client and live-preview React helpers for theme blocks.",
+    "license": "MIT",
+    "type": "module",
+    "sideEffects": false,
+    "main": "./dist/index.js",
+    "types": "./dist/index.d.ts",
+    "exports": {
+        ".": {
+            "types": "./dist/index.d.ts",
+            "import": "./dist/index.js"
+        },
+        "./client": {
+            "types": "./dist/client.d.ts",
+            "import": "./dist/client.js"
+        },
+        "./preview": {
+            "types": "./dist/preview.d.ts",
+            "import": "./dist/preview.js"
+        },
+        "./starter": {
+            "types": "./dist/starter.d.ts",
+            "import": "./dist/starter.js"
+        }
+    },
+    "files": [
+        "dist",
+        "starter",
+        "README.md"
+    ],
+    "publishConfig": {
+        "access": "public"
+    },
+    "repository": {
+        "type": "git",
+        "url": "git+https://github.com/BodhiMooij/blocklify.git",
+        "directory": "packages/preview"
+    },
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "prepublishOnly": "bun run build"
+    },
+    "peerDependencies": {
+        "react": ">=18",
+        "react-dom": ">=18"
+    },
+    "peerDependenciesMeta": {
+        "react": {
+            "optional": false
+        },
+        "react-dom": {
+            "optional": false
+        }
+    },
+    "devDependencies": {
+        "@types/react": "19.2.14",
+        "@types/react-dom": "19.2.3",
+        "typescript": "^5"
+    },
+    "keywords": [
+        "blocklify",
+        "cms",
+        "live-preview",
+        "headless"
+    ]
+}

package/starter/nextjs/.env.example

@@ -0,0 +1,7 @@
+# Blocklify CMS origin (no trailing slash)
+BLOCKLIFY_API_URL=https://localhost:3000
+# Same origin, exposed to the preview page so asset ids can load in the browser
+NEXT_PUBLIC_BLOCKLIFY_API_URL=https://localhost:3000
+
+# Read token from Admin → Access tokens
+BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_here

package/starter/nextjs/README.md

@@ -0,0 +1,12 @@
+# Next.js starter files
+
+Copy these into a new App Router app after `bun add @blocklify/preview`.
+
+```bash
+cp -R node_modules/@blocklify/preview/starter/nextjs/app ./app
+cp node_modules/@blocklify/preview/starter/nextjs/.env.example ./.env.local
+```
+
+Then set `BLOCKLIFY_API_URL`, `NEXT_PUBLIC_BLOCKLIFY_API_URL`, and `BLOCKLIFY_ACCESS_TOKEN` in `.env.local`.
+
+Register `http://localhost:3001/preview` under Space → Settings → Live preview URLs, and run this app on port 3001.

package/starter/nextjs/app/page.tsx

@@ -0,0 +1,25 @@
+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");
+    const body = entry?.content.body ?? [];
+
+    return (
+        <main>
+            <BlocklifyEntryView blocks={body} blockMap={blockMap} />
+        </main>
+    );
+}

package/starter/nextjs/app/preview/page.tsx

@@ -0,0 +1,17 @@
+"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…"
+        />
+    );
+}

package/starter/react/.env.example

@@ -0,0 +1,2 @@
+VITE_BLOCKLIFY_API_URL=https://localhost:3000
+VITE_BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_here

package/starter/react/README.md

@@ -0,0 +1,13 @@
+# React (Vite) starter files
+
+Copy these into a Vite React app after `bun add @blocklify/preview react-router-dom`.
+
+```bash
+cp node_modules/@blocklify/preview/starter/react/src/App.tsx ./src/App.tsx
+cp node_modules/@blocklify/preview/starter/react/src/main.tsx ./src/main.tsx
+mkdir -p src/pages
+cp node_modules/@blocklify/preview/starter/react/src/pages/PreviewPage.tsx ./src/pages/PreviewPage.tsx
+cp node_modules/@blocklify/preview/starter/react/.env.example ./.env
+```
+
+Register `http://localhost:5173/preview` under Space → Settings → Live preview URLs.

package/starter/react/src/App.tsx

@@ -0,0 +1,36 @@
+import { useEffect, useState } from "react";
+import {
+    BlocklifyEntryView,
+    createBlocklifyClient,
+    createStarterBlockMap,
+} from "@blocklify/preview";
+import type { BlocklifyBlock } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+});
+
+const client = createBlocklifyClient({
+    baseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+    accessToken: import.meta.env.VITE_BLOCKLIFY_ACCESS_TOKEN,
+});
+
+export default function App() {
+    const [blocks, setBlocks] = useState<BlocklifyBlock[]>([]);
+
+    useEffect(() => {
+        let cancelled = false;
+        client.getEntry("home").then((entry) => {
+            if (!cancelled) setBlocks(entry?.content.body ?? []);
+        });
+        return () => {
+            cancelled = true;
+        };
+    }, []);
+
+    return (
+        <main>
+            <BlocklifyEntryView blocks={blocks} blockMap={blockMap} />
+        </main>
+    );
+}

package/starter/react/src/main.tsx

@@ -0,0 +1,16 @@
+import { StrictMode } from "react";
+import { createRoot } from "react-dom/client";
+import { BrowserRouter, Route, Routes } from "react-router-dom";
+import App from "./App";
+import { PreviewPage } from "./pages/PreviewPage";
+
+createRoot(document.getElementById("root")!).render(
+    <StrictMode>
+        <BrowserRouter>
+            <Routes>
+                <Route path="/" element={<App />} />
+                <Route path="/preview" element={<PreviewPage />} />
+            </Routes>
+        </BrowserRouter>
+    </StrictMode>
+);

package/starter/react/src/pages/PreviewPage.tsx

@@ -0,0 +1,15 @@
+import { BlocklifyPreview, createStarterBlockMap } from "@blocklify/preview";
+
+const blockMap = createStarterBlockMap({
+    assetBaseUrl: import.meta.env.VITE_BLOCKLIFY_API_URL,
+});
+
+export function PreviewPage() {
+    return (
+        <BlocklifyPreview
+            blockMap={blockMap}
+            blocksFieldName="body"
+            emptyMessage="Waiting for content from the Blocklify editor…"
+        />
+    );
+}