React (Vite) guide

Clean React (Vite) install

Start from a Vite + React + TypeScript app, install @blocklify/preview, and point Blocklify live preview at your site. Prefer Next.js if you want App Router and server components out of the box.

Need a space and read token first? Getting started.

1.Prerequisites

  • Node.js 24.x (or current LTS) and bun / npm / pnpm.
  • Blocklify running (e.g. https://localhost:3000) with a space, an entry slug, and a read token.
  • Run the Vite app on a different port (this guide uses 5173).

2.Create the React app

Create the app in its own folder:

bunx create-vite@latest my-blocklify-site --template react-ts
# or: npm create vite@latest my-blocklify-site -- --template react-ts

cd my-blocklify-site
bun install

3.Install @blocklify/preview

bun add @blocklify/preview react-router-dom
# or: npm install @blocklify/preview react-router-dom

react-router-dom is used so /preview is a real path the admin iframe can open.

4.Environment variables

Vite only exposes vars prefixed with VITE_. Create .env:

VITE_BLOCKLIFY_API_URL=https://localhost:3000
VITE_BLOCKLIFY_ACCESS_TOKEN=blocklify_your_token_here

Restart vite after changing env files. Do not commit the token.

5.Add theme block components

Copy the starter pages from the package. They already render hero, text, image, and cta:

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

6.Add the preview page

// src/pages/PreviewPage.tsx
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…"
    />
  );
}

7.Wire a simple router

Mount /preview so the live preview URL resolves:

// src/main.tsx
import { StrictMode } from "react";
import { createRoot } from "react-dom/client";
import { BrowserRouter, Routes, Route } from "react-router-dom";
import { PreviewPage } from "./pages/PreviewPage";
import App from "./App";
import "./index.css";

createRoot(document.getElementById("root")!).render(
  <StrictMode>
    <BrowserRouter>
      <Routes>
        <Route path="/" element={<App />} />
        <Route path="/preview" element={<PreviewPage />} />
      </Routes>
    </BrowserRouter>
  </StrictMode>
);

Optional: in App.tsx, use createBlocklifyClient with import.meta.env.VITE_BLOCKLIFY_API_URL and VITE_BLOCKLIFY_ACCESS_TOKEN to render published entries on the home page.

8.Register the Live preview URL

  1. In Blocklify: space → Settings → Live preview URLs.
  2. Add:
    http://localhost:5173/preview
  3. Open an entry with a slug and confirm the iframe loads your Vite app. Click a block outline to focus its fields in the editor.

9.Run both apps

# Terminal A — Blocklify CMS
cd ../blocklify
bun run dev
# → https://localhost:3000

# Terminal B — Vite React site
cd ../my-blocklify-site
bun run dev
# → http://localhost:5173

More troubleshooting tips: Getting started → Troubleshooting.