Install the adapter
One package. It brings the client and the components with it.
npm install @bettercms-ai/astro The Astro adapter is @bettercms-ai/astro. It adds a bettercms() integration to your Astro config, a bettercms:client virtual module with typed loaders, draft preview through a signed cookie, and native .astro components that render a page built in the BetterCMS dashboard. It needs Astro 4 or later.
Six steps. The first five are the adapter, the sixth is what makes a publish show up.
Per page SEO comes back on the page object as metaTitle, metaDescription and metaJson. resolveSeo merges it over your site defaults with the same precedence the hosted renderer uses.
One package. It brings the client and the components with it.
npm install @bettercms-ai/astro The integration takes your API origin and workspace, or reads them from PUBLIC_BCMS_API_URL and PUBLIC_BCMS_WORKSPACE.
Draft mode and live reads need a server render, so set output to server.
import { defineConfig } from "astro/config";
import bettercms from "@bettercms-ai/astro";
export default defineConfig({
integrations: [
bettercms({
apiUrl: "https://api.bettercms.ai",
workspace: "my-workspace",
}),
],
output: "server",
}); Both values stay on the server and are never bundled to the client. Use a content:read key, or content:read:draft if you want previews.
BCMS_API_KEY=bcms_proj_...
BCMS_DRAFT_SECRET=<32 characters or more> One line teaches TypeScript about the virtual module and the Astro.locals the integration adds.
/// <reference types="@bettercms-ai/astro/env" /> Loaders take Astro, so they return drafts automatically when draft mode is on. loadPage, loadEntry, loadEntries and loadForms are all exported from the virtual module.
BcmsBlocks renders every block type the page builder can author, as plain class driven markup.
---
import { loadPage, loadForms } from "bettercms:client";
import BcmsBlocks from "@bettercms-ai/astro/components/BcmsBlocks.astro";
const page = await loadPage(Astro, "home");
const { items: forms, turnstileSiteKey } = await loadForms(Astro);
---
{page && (
<BcmsBlocks
blocks={page.blocks}
forms={forms}
turnstileSiteKey={turnstileSiteKey}
/>
)} Reads are cached, so an edit appears on the next fetch rather than instantly. For an immediate refresh, point the project revalidation webhook in Project settings at your host rebuild hook.
The Vercel, Netlify and Cloudflare pages on this site cover that step per host.
Draft preview and live reads require output: "server". A fully static Astro build can read published content at build time, and it cannot serve a draft, because there is nothing running to validate the preview token against.
BcmsBlocks, BcmsForm and BcmsImage emit plain, class driven markup and ship no CSS. That is deliberate, and it means the components are a rendering contract rather than a design system. You own every rule.
Reads are cached. Without a revalidation webhook pointed at your rebuild hook, a published edit shows up on the next fetch rather than on the next page view.
This adapter is the headless path: BetterCMS holds the content and you deploy the Astro site wherever you like. If you want BetterCMS to render and host the pages instead, that is BetterCMS Cloud and it is a different setup.
Yes. @bettercms-ai/astro is a first party adapter: a bettercms() integration for the Astro config, a bettercms:client virtual module with typed loaders, draft preview, and .astro components that render page blocks. It supports Astro 4 and later.
Yes, with output set to server. The integration adds two routes, one to enable draft mode against a signed token and one to disable it. Generate the preview link in the dashboard; visiting it validates the token, sets a signed cookie, and every loader returns draft content from then on. It needs BCMS_DRAFT_SECRET set, because that is what signs the cookie, and a key with the content:read:draft scope.
No. The Astro adapter is the headless path. BetterCMS holds the content, your Astro site reads it, and you deploy anywhere. BetterCMS Cloud is the other option, where BetterCMS renders and hosts the pages. Both are supported and they are different setups, not tiers of the same one.
BcmsImage renders an optimized image with a 1x and 2x srcset against the media transform endpoint. If you need URLs outside a component, @bettercms-ai/image-url is a chainable builder for the same endpoint: width, height, format, quality, fit and dpr.
First party App Router adapter: typed cache aware reads, tag revalidation, draft mode, and a generated llms.txt route.
A deploy hook rebuilds the site on publish, or a revalidate route updates one page in about a second.
A build hook rebuilds the site on publish. Three steps, no plugin, and one caveat about build minutes.
See BetterCMS running on your pages, not on a sample site.