@bettercms-ai/preview-runtime

Zero-config component previews for Next.js and Astro apps on BetterCMS.

You do not install or configure this package. BetterCMS runs it for you:

• In your repository's CI. When someone opens Output on a component in the BetterCMS dashboard, BetterCMS adds .github/workflows/bcms-component-validation.yml to your repository (once) and starts it. The workflow runs npx @bettercms-ai/preview-runtime validate, which builds a preview of your app as it is, renders the component in a real browser at each viewport, checks it, and reports the result.
• On BetterCMS hosting. The preview built in CI is what the dashboard shows, rendered by your own code with live content.

Nothing is written to your repository except that one workflow file. Routes are generated into the CI checkout for the build and removed afterwards.

What it needs to know

Which file implements a component. The agent that writes a component records it through the BetterCMS MCP tool set_component_source (for example src/components/sections/Hero.astro, or components/Hero.tsx with an export name).

Commands

# Build a preview runtime from an app (used by `validate`; useful when debugging locally)
bcms-preview build --manifest manifest.json --out .bcms-preview-release [--cwd path/to/app]

# Validate one component (CI only; configured by BCMS_* environment variables the workflow sets)
bcms-preview validate

manifest.json:

{ "components": [{ "id": "cmp_1", "source": { "path": "src/components/Hero.astro" } }] }

Sections extracted from pages

A component does not have to be a standalone file with its fields as props. A section npx @bettercms-ai/convert --componentize extracted from a page (a file starting // @bettercms-ai/convert section v…) is recognised by that marker and rendered with its section contract: <Section blockId="bcms-preview" overrides={props} page={{}} />, so the live props arrive as the instance's own copy.

Components with no file

A component placed on a page, or used in the project Layout (navigation, footer), needs no recorded file. The manifest lists it as kind: "page"; the preview renders that real route of your app — its loops, child components, collections and page styles exactly as deployed — keeps only the component's own element (data-bcms-block, else the element holding its fields, else the layout's <header>/<footer>), and writes the live props onto it through the same data-bcms-field / data-bcms-layout-field / data-bcms-props attributes the site already declares. A recorded file still wins when there is one.

v1 limits: scripts inside the kept element do not run, so a client island renders its server HTML without hydrating (validation is unaffected). The Next.js page path (render → render-page) is untested against a real Next app yet; Astro is verified.

A failed validation reports what broke — the app server's own error lines first — and the dashboard shows it under "Runtime + console".

Batch validation

One run can validate several components against a single build. When the dispatch carries a batch (BCMS_BATCH, a JSON array of { requestId, componentId, familyKey, nativeViewports }), the validator builds and uploads the runtime once, starts one browser, and validates each component in turn — a component that cannot be validated is reported for that component and the rest carry on. Without BCMS_BATCH it validates the single component named by BCMS_REQUEST_ID / BCMS_COMPONENT_ID / BCMS_FAMILY_KEY / BCMS_NATIVE_VIEWPORTS, as before. The step fails when any component could not be validated.

How a preview renders

• Astro: built with output: "server" and @astrojs/node, so .astro components render on the server with the props the dashboard sends.
• Next.js: built with output: "standalone", so client components and async server components render the way they do in your app.

The preview is served under /__bettercms/component-preview/ and only accepts a short-lived, signed session from the BetterCMS dashboard.