Integration · Framework

BetterCMS and 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.

Package
@bettercms-ai/astro
Requires
Astro 4 or later
Category
Framework

Set it up

Six steps. The first five are the adapter, the sixth is what makes a publish show up.

  1. 01 Install the adapter
  2. 02 Add the integration
  3. 03 Set the server environment
  4. 04 Reference the types
  5. 05 Read a page and render it
  6. 06 Rebuild when content publishes

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.

  1. 01

    Install the adapter

    One package. It brings the client and the components with it.

    terminal
    npm install @bettercms-ai/astro
  2. 02

    Add the integration

    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.

    astro.config.mjs
    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",
    });
  3. 03

    Set the server environment

    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.

    .env
    BCMS_API_KEY=bcms_proj_...
    BCMS_DRAFT_SECRET=<32 characters or more>
  4. 04

    Reference the types

    One line teaches TypeScript about the virtual module and the Astro.locals the integration adds.

    src/env.d.ts
    /// <reference types="@bettercms-ai/astro/env" />
  5. 05

    Read a page and render it

    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.

    src/pages/index.astro
    ---
    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}
      />
    )}
  6. 06

    Rebuild when content publishes

    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.

What it does not do

  • Draft mode needs a server

    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.

  • The markup is unstyled

    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.

  • Publishing is not instant by default

    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.

  • It does not host the site

    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.

Questions people ask

  • 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.

Your next website starts here

See BetterCMS running on your pages, not on a sample site.