A static Astro site + a headless CMS is three moving parts (and one thing every tutorial skips)

Fetch at build. One route per entry. Webhook that rebuilds on publish. That's the whole integration — Astro does the first two natively, so most of the work is wiring.

The fetch goes in the frontmatter script, which runs on the server at build time:

---
const res = await fetch('https://api.draftbase.co/delivery/entries?templateId=blogPost', {
  headers: { Authorization: `Bearer ${import.meta.env.DRAFTBASE_KEY}` },
});
const { items } = await res.json();
---

No key in the bundle. No API call from the browser. No loading spinner.

A page per entry is src/pages/blog/[slug].astro plus getStaticPaths, returning params for the URL and props so the page doesn't fetch the same entry twice.

The part every tutorial skips

Delivery APIs serve published content only. Your build literally cannot see a draft. So editors have no preview, and you find that out the day after launch.

Two workable fixes:

• On-demand preview route. Add an adapter, set export const prerender = false on one route, read drafts from the management API with a server-side token. The rest of the site stays static.
• Preview deploy. A branch that pulls drafts too. Simpler to reason about, costs an extra build.

First one if editors preview constantly. Second one if it's occasional. Either way the management token stays server-side — it can write.

Four things that break in production

• Silent truncation. Delivery APIs cap page size. Nobody follows the cursor. Site looks fine at 40 entries, drops posts at 101.
• Stale pages after a delete. Webhook fires on publish only, so a removed post keeps its page until some unrelated deploy.
• Images served from the CMS origin. Undoes the whole CDN benefit.
• A broken build takes the site down. Confirm your host keeps the last good deploy live.

Full guide has the code for each step, the MDX rendering choice (compile at build vs. client island), and Astro-vs-Next.js for CMS-backed sites:

How to Build a Static Astro Site with a Headless CMS →

Samples use Draftbase — our headless CMS. Rich text is plain MDX, which Astro renders natively, so there's no converter to maintain. Hobby free, Startup $49/mo.