How to Integrate Astro with Your Headless CMS

What is Astro?

Astro is a web framework for building content-heavy sites with static HTML by default and server rendering when you need it. It uses an island architecture, so interactive components from React, Vue, Svelte, and other frameworks only hydrate where needed. Teams use Astro for marketing sites, documentation, blogs, ecommerce frontends, and landing pages where page speed and developer control both matter.

Why integrate Astro with a headless CMS?

Astro works well when content is predictable, typed, and available at build time or request time. If every pricing page, docs article, author bio, and product landing page lives in Git as Markdown, developers become the publishing queue. A small copy edit can turn into a pull request, preview build, review cycle, merge, and production deploy.,Connecting Astro to a headless CMS category tool moves that editing work out of Git while keeping Astro’s performance model intact. Astro can fetch content during static builds with getStaticPaths(), render dynamic pages through server endpoints, or mix both approaches. With Sanity, the AI Content Operating System, content is structured as JSON in the Content Lake, so Astro gets fields like title, slug, heroImage, author, and relatedProducts instead of parsing HTML blobs.,The event flow matters. Real-time webhooks can trigger an Astro rebuild on Vercel, Netlify, or another host when content is published, updated, or deleted. For more control, Sanity Functions can run server-side logic on content mutations, fetch exactly the fields Astro needs with GROQ, and call a protected Astro API route. The trade-off is that static Astro sites still need a build step for changed pages, while SSR Astro apps can show new content faster at the cost of runtime infrastructure.

Architecture overview

A typical Astro integration starts with editors publishing structured documents in Sanity Studio. Those documents are written to the Content Lake as typed JSON. Astro can pull that content directly with @sanity/client during build time, for example inside getStaticPaths() for blog routes, or at request time inside Astro API routes and server-rendered pages. GROQ selects only the fields the route needs, such as slug, title, body, author->name, and category->slug. When a publish event happens, a Sanity webhook can call an Astro endpoint like /api/sanity-publish, or a Sanity Function can handle the mutation event without separate server infrastructure. The handler verifies the request, fetches the current document from the Content Lake with GROQ, and then triggers the next step, such as a Vercel Deploy Hook, Netlify Build Hook, or an internal Astro API route that clears cached data. End users receive static HTML from a CDN for prebuilt pages, or a server-rendered Astro response when you choose SSR for faster publish visibility.

Common use cases

Step-by-step integration

1. 1

   Create the Astro project

   Astro doesn’t require an account. Create the app with npm create astro@latest, choose static output or an adapter such as Vercel, Netlify, or Node for SSR, then install the Sanity client with npm install @sanity/client.

2. 2

   Add Sanity project credentials

   Create or select a Sanity project, then add SANITY_PROJECT_ID, SANITY_DATASET, SANITY_API_VERSION, and a read token if you need draft or private content. Public published content can often use the CDN without a token.

3. 3

   Model Astro-ready content in Sanity Studio

   Define schemas for the pages Astro will render. A marketing page might include title, slug, heroImage, body, seoTitle, seoDescription, and modules. A docs page might include title, slug, section, order, body, and relatedArticles.

4. 4

   Fetch content in Astro

   Use @sanity/client in Astro pages, layouts, or API routes. For static routes, fetch slugs in getStaticPaths() and render each page at build time. For SSR routes, fetch by slug during the request.

5. 5

   Create the publish trigger

   Set up a Sanity webhook that fires on create, update, and delete for the document types Astro uses. Point it at an Astro API route, or use a Sanity Function to fetch the changed document and call your hosting provider’s deploy hook.

6. 6

   Test previews, builds, and deletes

   Publish a test document, confirm the webhook fires, confirm your Astro build or cache update runs, and check the final URL. Also test slug changes and deleted documents, since those cases often need redirects or 404 handling.

Code example

import type { APIRoute } from 'astro';
import { createClient } from '@sanity/client';

const sanity = createClient({
  projectId: import.meta.env.SANITY_PROJECT_ID,
  dataset: import.meta.env.SANITY_DATASET,
  apiVersion: '2025-02-06',
  token: import.meta.env.SANITY_READ_TOKEN,
  useCdn: false,
});

export const POST: APIRoute = async ({ request }) => {
  const { _id } = await request.json();
  const id = _id?.replace('drafts.', '');

  const page = await sanity.fetch(
    `*[_id == $id][0]{_id,title,"slug":slug.current,"author":author->name}`,
    { id }
  );

  if (!page?.slug) return new Response('Ignored', { status: 202 });

  await fetch(import.meta.env.DEPLOY_HOOK_URL, {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ source: 'sanity', slug: page.slug }),
  });

  return Response.json({ ok: true, queued: page.slug });
};

How Sanity + Astro works

CMS approaches to Astro

Keep building

Explore related integrations to complete your content stack.