# Sanity and Astro

Sanity gives Astro developers a structured content backend with real-time collaboration, a customizable editing environment, and APIs designed for both static and server-rendered sites. Sanity provides the content infrastructure while Astro handles the frontend.

## Get started

- [Quickstart](https://www.sanity.io/docs/astro-quickstart): get a working Astro + Sanity project running in minutes.
- [Starter template](https://www.sanity.io/templates/astro-sanity-clean): clone a preconfigured project with Sanity Studio and content fetching already wired up.
- [Blog guide](https://www.sanity.io/docs/developer-guides/sanity-astro-blog): build a complete blog with Astro and Sanity from scratch, with more details and explanation than the quick start.

## The @sanity/astro integration

`@sanity/astro` is the official Astro integration for Sanity. It configures the Sanity Client as a virtual module in your Astro project and optionally embeds Sanity Studio on a route.

Install it inside an existing Astro project:

**Terminal**

```sh
npx astro add @sanity/astro @astrojs/react
```

This adds `@sanity/astro` to your `astro.config.mjs` and makes the Sanity client available through the `sanity:client` virtual module. For full configuration options, see [Configuring @sanity/astro](https://www.sanity.io/docs/astro/configure-sanity-astro).

The integration provides:

- **Sanity Client** (`sanityClient`): a pre-configured client available via `import { sanityClient } from "sanity:client"`.
- **Embedded Studio**: mount Sanity Studio as a route in your Astro app using `studioBasePath`.
- **Visual Editing**: click-to-edit overlays for draft content in the Presentation Tool (requires SSR).
- **Stega encoding**: invisible source mapping that connects rendered content back to its source documents.

> [!NOTE]
> `@astrojs/react` is only needed if you plan to embed Sanity Studio or use the Visual Editing component in your project.

## How Astro differs from Next.js

If you're coming from `next-sanity`, there are some differences worth understanding.

Astro defaults to static site generation. Pages are pre-rendered at build time, which means content is fetched once during the build rather than on every request. This is great for performance but means content updates require a rebuild unless you switch to [server-side rendering](https://www.sanity.io/docs/astro/static-and-server-rendering).

The `@sanity/astro` integration is lighter than `next-sanity`. It focuses on client configuration, Studio embedding, and basic Visual Editing. Some features available in `next-sanity` don't have equivalents here:

- **No Live Content API:** `next-sanity` provides `defineLive` and `SanityLive` for automatic real-time content updates and cache revalidation. Astro doesn't have an equivalent. Content updates require a rebuild (static mode) or a page refresh (SSR mode) unless you [implement the live content integration](https://www.sanity.io/docs/developer-guides/live-content-guide) yourself.
- **No built-in cache revalidation:** `next-sanity` integrates with the Next.js data cache for time-based, tag-based, and path-based revalidation. In Astro, caching behavior depends on your rendering mode and hosting adapter.
- **No webhook validation helper:** `next-sanity` exports `parseBody` for secure webhook signature validation. For Astro, you'd implement webhook handling through your hosting platform or a custom API endpoint.

## Key features

### Visual Editing

Visual Editing lets content editors click directly on rendered content in the Presentation Tool to open the corresponding field in the Studio. It uses stega encoding to invisibly map rendered text back to its source document and field.

Visual Editing in Astro requires server-side rendering. Static pages can't encode stega strings at request time. Set `output: 'server'` in your Astro config for project-wide SSR, or keep the default `output: 'static'` and add `export const prerender = false` to individual pages that need server rendering. See [Visual Editing for Astro](https://www.sanity.io/docs/visual-editing/astro-visual-editing) for setup instructions.

### Embedded Studio

You can mount Sanity Studio as a route inside your Astro application using the `studioBasePath` option. This means your content editing environment lives at a path like `/admin` in the same deployment as your frontend. See [Embedding Studio in Astro](https://www.sanity.io/docs/astro/embedding-studio-in-astro) for configuration details.

### Portable Text and images

Sanity stores rich text as Portable Text, a JSON-based format that's framework-agnostic and queryable. The community-maintained `astro-portabletext` library renders Portable Text in Astro components with support for custom block types and annotations. For images, `@sanity/image-url` generates CDN URLs with on-demand transforms, automatic optimization, and responsive sizing. See [Images and Portable Text in Astro](https://www.sanity.io/docs/astro/images-and-portable-text-astro) for usage patterns.

## Next steps

- [Astro quickstart](https://www.sanity.io/docs/astro-quickstart): set up a new project from scratch.
- [Configure @sanity/astro](https://www.sanity.io/docs/astro/configure-sanity-astro): client setup, environment variables, and integration options.
- [Query content in Astro](https://www.sanity.io/docs/astro/query-content-astro): fetching data with GROQ in `.astro` components.
- [Static and server rendering](https://www.sanity.io/docs/astro/static-and-server-rendering): choose the right rendering mode for your project.