An Astro and Sanity site architecture splits code and content into two independent layers: Astro builds static pages at build time, while Sanity stores content in its own cloud storage and serves it through an API. The marketing team edits copy, images, and page structure in the Sanity Studio visual editor, without touching code and without waiting for a release. The developer gets typed content schemas, edit versioning, and the speed of a static site.
Across projects we see the same pattern over and over: the site runs on a modern stack, but any text change on the landing page turns into a developer ticket and a wait for release. The marketing team simply cannot publish a Friday-evening promotion if it requires a pull request and a deploy.
The issue isn’t Astro as a framework - it handles static generation perfectly well. The issue is where the content lives: in .md files in the repository, or hardcoded directly into components. Splitting the two apart with a headless CMS solves that problem, but not every CMS pairs equally well with a static site generator.
Below: how the Astro and Sanity pairing works, what it gives the team, and when you don’t need it.
For an agency or startup where marketing moves faster than the dev cycle, the gap between content and code is a concrete loss of money. A campaign misses its deadline because the landing page for it can’t be updated without a developer, and the developer is busy with something else in the current sprint.
Headless CMS: a content management system with no built-in page rendering - it stores data and serves it through an API, while the frontend decides how to display it.
Why separating content from code solves a real problem
A classic site on a static generator stores content alongside code: in Markdown files in the repository, or directly in component markup. Any text edit goes through the same path as a code change - commit, review, deploy.
For a team of one or two developers, that’s tolerable. For an agency with several clients, or a startup where marketing ships landing pages every week, it’s a bottleneck. Every text edit competes for a developer’s attention against bugs and features.
A headless CMS solves this literally - it removes content from the repository. Sanity stores content separately, in the cloud, and serves it through an API at build time. Code and content are versioned and deployed independently of each other.
The developer describes the field schema once - what an article is, what a service page is, which fields are required. After that, marketing fills in and changes content within that schema on their own, without a developer involved in every edit.
This isn’t an abstract architectural choice for its own sake. It’s a concrete answer to “why does updating text on the site take three days instead of ten minutes.”
If a site already exists and runs on a setup with content baked into the code, moving to this architecture is an upgrade to an existing site, not a from-scratch project. The schema can be introduced gradually, starting with the sections edited most often - the blog, campaign landing pages, service pages.
How the Astro and Sanity pairing is architected
Technically the pairing is built on three components: content storage, a data-query mechanism, and a strategy for updating the built site.
Content Lake: Sanity’s cloud content store, where data lives as structured JSON documents rather than files. It’s not a database in the usual sense - it’s a managed service that Astro calls through an API at build time.
The content schema is described in Sanity Studio - a separate editorial application deployed alongside the site or on its own. The developer defines document and field types in schema code: title, image, related documents, nested text blocks.
Reading data on the Astro side goes through GROQ - Sanity’s own query language, designed to fetch nested and related documents in a single query, without a batch of separate API calls. The official @sanity/astro plugin wires the Sanity client into the project and simplifies typing query results; GROQ syntax and the current API version are documented in the Sanity docs, and working with data sources on the Astro side is covered in Astro Content Layer.
Next comes the generation strategy. By default Astro builds pages statically: HTML is generated at build time and served as plain files, with no API call on every visitor request. That gives you the speed of static files, but it raises a question - how fast does a change in Sanity Studio reach the live site.
This is where incremental revalidation (ISR) or on-demand revalidation comes in: instead of rebuilding the whole site, only the page whose content changed gets updated, via a webhook from Sanity to the host. In practice this means an edit in Studio reaches production in seconds, not after a full build cycle.
What the marketing team gets
The marketing team gets an interface where content edits don’t depend on the dev team’s task queue.
Sanity Studio is a visual editor with fields configured for each specific content type: not a bare text field, but a form with an image preview, related-article selection, and required-field validation. It’s harder to make a structural mistake than in raw Markdown.
Key capabilities for marketing:
- Editing text, images, and metadata without access to code or the repository.
- Previewing changes before publishing - you can see how a page will look before it’s visible to visitors.
- Document version history: any edit can be rolled back, and you can see who made it and when.
- Real-time collaborative editing when several people work on the content.
- Publishing without a developer deploy - content reaches the site via webhook and revalidation, not
git push.
In practice this closes a specific scenario: a marketer builds a campaign landing page on a Friday evening and publishes it themselves, without waiting for Monday and a free slot on a developer’s calendar.
What the developer gets
The developer gets predictable typing and less manual work on routine content edits.
The schema in Sanity Studio is described in code - which means the content structure is versioned in git along with the rest of the project, rather than living only in the head of whoever designed it. Document types can be turned into TypeScript types for queries, and a data-structure error shows up at build time instead of in the user’s browser.
Practical benefits for development:
- Content is decoupled from code deploys: a text edit doesn’t require running CI/CD over a typo.
- GROQ queries fetch exactly the fields and relations a given page needs, without extra load on the API.
- Astro’s static generation delivers strong baseline Core Web Vitals with no manual tuning.
- Content versioning in the Content Lake makes it easy to roll back an editor’s mistake.
The cost is an extra infrastructure layer and the need to keep the schema up to date. That’s not free, but it’s usually cheaper than manual code edits for every typo.
Step-by-step setup
The order of work is typical for most Astro projects, though the scope of each step depends on how many content types the site has.
1. Content schema in Sanity Studio
Start by describing document types: page, blog post, service card, menu item. For each type, define the fields - text, image, a link to another document, an array of nested blocks.
Design the schema around the site’s real pages, not in the abstract. If the site has service pages with an identical structure, they should share one document type with the same set of fields, rather than a separate schema for each page.
2. Integration via the official plugin
The official @sanity/astro plugin wires the Sanity client into the project and sets up the base configuration - project ID, dataset (production, staging), and API version. Once installed, Astro gets access to the client for GROQ queries and, if needed, to visual editing through Sanity Studio embedded in the same project.
3. GROQ queries at build time
Each page or page collection in Astro builds its own GROQ query: which document fields it needs, which related documents to pull in, and in what order to sort the results. The query runs inside the static path-generation functions (getStaticPaths) at build time, and the result turns into finished HTML.
4. ISR and on-demand revalidation
The final step is connecting a webhook from Sanity to the host, so a content change triggers revalidation of the specific page rather than a rebuild of the whole site. The exact mechanism depends on the host: some providers support built-in on-demand revalidation, others require a separate serverless function that receives the webhook and triggers a targeted rebuild.
Limitations and when it’s overkill
The Astro and Sanity pairing isn’t a universal solution for every site - it has a cost, and sometimes that cost doesn’t pay off.
Limitations worth weighing:
- An extra infrastructure layer: Content Lake, schema, plugin, webhook revalidation - more moving parts than content sitting directly in repository files.
- A delay between an edit in Studio and it appearing on the site if on-demand revalidation isn’t set up - content only updates on the next full rebuild.
- Sanity’s free tier is capped on user count and API request volume; a large editorial team will need a paid plan.
- Migrating back out is hard: content is stored in Sanity’s proprietary format, and moving to another CMS is a separate project, not a one-off export.
For a site of 5-10 static pages edited by the same developer once a quarter, a headless CMS is unnecessary complexity. Content collections directly in Astro’s code are enough here - content in Markdown, with no separate cloud platform and its overhead.
The pairing pays off when content changes more often than code, and it’s edited by someone other than a developer. If that condition doesn’t hold, the extra infrastructure layer just adds cost without a payoff.
A real case, in numbers
On projects with a blog and regular campaign landing pages, the difference before and after moving to this architecture shows up most clearly in the publishing cycle.
Before: a text edit on a landing page went through a developer ticket, a branch, review, and a deploy. Based on our observations on similar projects, a typical cycle took one to three business days - depending on the developer’s workload and task queue.
After: a marketer publishing an edit in Sanity Studio with webhook revalidation takes anywhere from a few seconds to a couple of minutes - the time needed to rebuild and serve that specific page, not the whole site.
On build speed: for a site of 200-500 pages, a full Astro rebuild typically fits in 1-3 minutes. Revalidating a single page takes seconds, because only one route is rebuilt, not the entire site.
These numbers are a benchmark for typical projects of this scale, not a guaranteed result: actual speed depends on the host, the volume of content, and query complexity.
Who this architecture fits
The Astro and Sanity pairing fits teams where marketing publishes content more often than the dev team is ready to deploy code: agencies running several projects, startups with an active blog and regular campaign landing pages, companies where the site is the main lead-generation channel. If you’re building such a site from scratch, it makes sense to build in a headless CMS architecture from the start, rather than migrating content out of code later.
Frequently asked questions
How does Sanity differ from Contentful or Strapi for pairing with Astro?
The key difference is the hosting model and query language. Sanity is a fully managed SaaS with its own GROQ query language and the Sanity Studio visual editor, which you can customize with code. Strapi can be self-hosted on your own infrastructure, while Contentful is closer to Sanity’s SaaS model but uses REST and GraphQL instead of GROQ. A detailed comparison of these options is in Sanity vs Contentful vs Strapi.
Do you need a separate server for Sanity Studio?
Not for storing content - the Content Lake is fully managed by Sanity. Studio itself is a React application that can be deployed as a static site on any host, or embedded directly into an Astro project as a separate route. No separate backend server is needed, unlike a self-hosted CMS such as Strapi.
What happens to the site if Sanity becomes unavailable?
Already-built static pages keep being served as plain files regardless of Sanity’s availability - that’s the advantage of static generation over a setup where a page renders on every request. Only publishing new edits is affected: while the Content Lake is unavailable, GROQ queries at the next build won’t run.
Can Sanity be used with frameworks other than Astro?
Yes, Sanity isn’t tied to a specific frontend and works with Next.js, Remix, SvelteKit, and other frameworks through official or third-party clients. The official @sanity/astro plugin is just one integration package; the Content Lake and GROQ model itself doesn’t depend on any particular framework.
How long does migrating an existing site to Astro and Sanity take?
It depends on the volume of content and the number of unique page types. For a site with a blog and a dozen standard service page types, migrating the schema, content, and setting up revalidation usually fits within a few weeks. A precise estimate requires reviewing the current content structure and the target schema.
If you have an Astro site where every text edit runs into a developer queue - describe the task to the Exceltic.dev team. We’ll review the current architecture and estimate the scope of moving to Sanity.