@saacms/host-astro

The Astro host adapter for saacms. Knows how to:

1. Generate .astro route files into src/pages/<page-url>.astro for Pages and Page templates (per ADR 0003).
2. Emit the small mount file at src/pages/api/saacms/[...slug].ts that binds saacms's runtime handler into Astro's API surface (per ADR 0001).
3. Generate per-Block preview routes the Puck canvas fetches at edit time (per ADR 0004 Mode 2).

This is the only host adapter shipped in v1 alpha (per ADR 0024). Other hosts (host-nextjs, host-sveltekit, host-nuxt) follow in v1.x.

Reading order (relevant ADRs)

• ADR 0001 — Content compiler + serverless runtime
• ADR 0003 — saacms owns the host's route filesystem
• ADR 0004 — Block authoring: dual mode + preview-fetch
• ADR 0007 — Render mode is per-Page-template
• ADR 0009 — Media as Collection kind (repo vs bucket)
• ADR 0021 — Rendering and caching across the coupling spectrum
• ADR 0024 — v1 alpha scope: Astro + Cloudflare

Status

Scaffold. Interface shape and template files are defined; the route emitter is a stub. Real .astro source emission lands alongside the v1.0 alpha milestone.

Why Astro, why now

Per ADR 0024 — Astro's "lightest framework that works" philosophy aligns with the saacms performance philosophy (ADR 0022 P1). Astro Server Islands give us PPR-equivalent partial rendering without framework-specific magic. Cloudflare Pages + D1 + R2 + Astro is the cleanest single stack to prove the architecture against before fanning out to Next.js / SvelteKit / Nuxt in v1.x.

Templates

Three text templates live under templates/. They are intentionally not TypeScript — they are emitted verbatim by the saacms compile step into the user's project, where their imports refer to user-side files (../../../../saacms.config.ts, ../../../saacms/blocks/*.astro).

• templates/api-mount.ts.txt — the file saacms init writes to src/pages/api/saacms/[...slug].ts.
• templates/preview-route.astro.txt — the per-Block preview route template (ADR 0004 Mode 2).
• templates/page-route.astro.txt — the per-Page route template, emitted by the route emitter.

Known reconciliation TODO

The local HostAdapter interface in src/types.ts diverges slightly from the canonical interface exported by @saacms/core (src/host/index.ts). This is a v1-scaffold artefact — subagents wrote both in parallel without final cross-check. To do before first real implementation pass:

• Adopt core's GenerateRouteContext / GeneratedRoute / MountTemplate shape verbatim
• Drop _core-shim.ts (use @saacms/core brand types directly)
• Rename assetRoot() → assetRoot (readonly property, per core)
• Rename previewRouteTemplate(slug) → fold into generatePreviewRoute(ctx) per core's contract