@bettercms-ai/react

BetterCMS for client-rendered React apps (Vite, CRA, any SPA). For Next.js use @bettercms-ai/next, for Astro @bettercms-ai/astro.

npm i @bettercms-ai/react

VITE_BCMS_API_URL=https://api.bettercms.ai
VITE_BCMS_WORKSPACE=your-workspace
VITE_BCMS_PROJECT_ID=your-project-id

// main.tsx
import { BcmsProvider } from "@bettercms-ai/react";
createRoot(el).render(<BcmsProvider env={import.meta.env}><App /></BcmsProvider>);

// a page
import { BcmsBlocks, usePage, useComponents } from "@bettercms-ai/react";
export function Home() {
  const { data: page } = usePage("home");
  const { data: components } = useComponents();
  return page ? <BcmsBlocks blocks={page.blocks} components={components} /> : null;
}

Hooks: usePage(slug), useEntry(slug), useEntries(opts), useLayout(), useComponents(), useBcmsQuery(key, read); each returns { data, error, loading }.

Components (the same markup as @bettercms-ai/next): BcmsBlocks, BcmsSections (inside <BcmsProvider> and given no blocks, <BcmsSections page="home"> reads the page's order itself, so the app's own sections render in the order the CMS page lists them), BcmsSection, BcmsField, BcmsImage, BcmsButton, BcmsForm, BcmsSearch, and BcmsDraftBridge, which lets the editor re-render drafts with your own components.

Your own components, editable

Spread a binding onto your own elements and the visual editor binds them:

import { entryAttrs, entryField, fieldAttrs, sectionRootAttrs } from "@bettercms-ai/react";

<h1 {...fieldAttrs("hero-title", page.fieldStyles)}>{title}</h1>
<article {...entryAttrs(post)}><h3 {...entryField(post, "title")}>{post.data.title}</h3></article>

Live

Every hook re-reads when content is published (pass liveSrc, or set VITE_BCMS_LIVE_URL), and when the visual editor asks the page to re-render. Re-reading keeps the current page on screen until the new data arrives. useBcms().refresh() re-reads on demand. In draft mode the provider also stamps <html data-bcms-draft="1"> and loads the click-to-edit overlay.

Draft mode

No server needed. The editor's "Preview on site" link opens /api/draft?token=…&redirect=/page on your site; an SPA host serves your app there, and <BcmsProvider> checks the token with BetterCMS, keeps it for the tab and moves to redirect. Reads then return drafts. useBcms().exitDraft() leaves draft mode. Set draftPath on the provider if your app uses another path (and the same path in the project's integration settings).

Your host must serve the app at that path, as it does for any client-side route: Netlify /* /index.html 200 in _redirects, a Vercel rewrite of /api/draft to /index.html (Vercel keeps /api for functions otherwise), and in vite dev no proxy on /api. GitHub Pages cannot rewrite: set draftPath to a path your app serves (/draft) and the same path in the integration settings. A token the backend refuses, or a check that cannot reach it, leaves the app published; an expired token is dropped the next time the app loads.