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 install3.Install @blocklify/preview
bun add @blocklify/preview react-router-dom
# or: npm install @blocklify/preview react-router-domreact-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_hereRestart 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 ./.env6.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
- In Blocklify: space → Settings → Live preview URLs.
- Add:
http://localhost:5173/preview - 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:5173More troubleshooting tips: Getting started → Troubleshooting.