@sanity/astro

The Official Sanity integration for Astro

This integration enables the Sanity Client in your Astro project and lets you embed Sanity Studio on a route. Astro is an all-in-one web framework that supports a range of UI languages and can be deployed in most places.

• Installation
  • Manual installation of dependencies
  • Adding types for sanity:client
• Usage
  • Setting up the Sanity client
  • Embedding Sanity Studio on a route
• Rendering rich text and block content with Portable Text
• Presenting images
  • Resources

Installation

In your Astro project, run the following command to install the Sanity integration:

npx astro add @sanity/astro @astrojs/react

Note: @astrojs/react is only needed if you plan to embed a Sanity Studio in your project.

Manual installation of dependencies

npm install @astrojs/react @sanity/astro @types/react-dom @types/react react-dom react

Adding types for sanity:client

This integration leverages Vite.js' virtual modules with Astro's naming convention (e.g. astro:assets). Since it's not possible to automatically include module declarations from npm packages, you'll have to add the following line to the env.d.ts file that usually recides in the src folder of an Astro project:

/// <reference types="astro/client" />
/// <reference types="@sanity/astro/module" />

You might have to restart the TS Server running in your code editor to get it to resolve types after updating this file. The easiest way to do this is to restart the application.

Usage

Setting up the Sanity client

Configure the integration in your astro.config.mjs file. The configuration options and methods are the same as for @sanity/client:

import sanity from "@sanity/astro";
import { defineConfig } from "astro/config";

// https://astro.build/config
export default defineConfig({
  integrations: [
    sanity({
      projectId: "<YOUR-PROJECT-ID>",
      dataset: "<YOUR-DATASET-NAME>",
      // Set useCdn to false if you're building statically.
      useCdn: false,
    }),
  ],
});

This enables the use of sanityClient in your template files. For example:

---
// /blog/index.astro
import { sanityClient } from "sanity:client";

const posts = await sanityClient.fetch(`*[_type == "post" && defined(slug)] | order(publishedAt desc)`);
---

<h1>Blog</h1>
<ul>
  {posts.map((post) => (
    <li>
      <a href={"/posts/" + post.slug.current} class="post-link">
        {post.title}
      </a>
    </li>
  ))}
</ul>

Check out this guide for a more elaborate introduction to how to integrate content from Sanity into Astro. You can also look in the examples folder in this repository for complete implementation examples.

Embedding Sanity Studio on a route

Sanity Studio is a customizable content workspace where you can edit your content. It‘s a Single Page Application that you can keep in its own repository, together with your Astro project as a monorepo, or embedded in your website.

To initialize a Studio in a dedicated folder, you can run npm create sanity@latest and follow the instructions.

This integration lets you embed a Sanity Studio on a route in your Astro project. To enable it:

1. Create a new file in your project root called sanity.config.ts (or .js)
2. Add the following code, and add your projectId and dataset to it:

// sanity.config.ts
import { defineConfig } from "sanity";
import { deskTool } from "sanity/desk";

export default defineConfig({
  name: "project-name",
  title: "Project Name",
  projectId: "<YOUR-PROJECT-ID>",
  dataset: "<YOUR-DATASET-NAME>",
  plugins: [deskTool()],
  schema: {
    types: [
      /* your content types here*/
    ],
  },
});

You can use this configuration file to install plugins, add a schema with document types, add customizations etc. Note that the Studio will be using Astro‘s development server which is built on top of Vite.

1. Add the following to your astro.config.mjs:
   • output: 'hybrid': Required since the Studio is a client-side application.
   • studioBasePath: '/admin': The route/path for where you want to access your studio
   • Import the React integration for Astro, and add it to the integrations array.

// astro.config.mjs
import sanity from "@sanity/astro";
import { defineConfig } from "astro/config";
import react from "@astrojs/react";

export default defineConfig({
  output: "hybrid",
  integrations: [
    sanity({
      projectId: "3do82whm",
      dataset: "next",
      // Set useCdn to false if you're building statically.
      useCdn: false,
      // Access the Studio on your.url/admin
      studioBasePath: "/admin",
    }),
    react(),
  ],
});

1. Since you have set output: 'hybrid' (or server), you have to add a deployment adapter to your Astro config as well. Astro offers a range of adapters depending on where you want to host your website.

2. You have to enable CORS origins for authenticated requests for the domains you're running your website project on. The Studio should automatically detect and let you add this when you access the Studio on a new URL. Typically you need to add your local development server URL and your production URL to the CORS origin settings. It's important that you only enable CORS for authenticated requests on domains that you control.

Rendering rich text and block content with Portable Text

Sanity uses an open specification for rich text and block content called Portable Text. Portable Text stores content from the editor as JSON (and not HTML or Markdown). This makes it platform/framework agnostic, and also queryable (for example, you can query for blog posts that have more than 4 TypeScript code blocks).

While it's possible to loop over the JSON structure manually, we recommend using a Portable Text library to do the heavy lifting. It will automatically render the default editor configuration to HTML. If you do customizations like adding custom block types, then you need to map those to a component in your front end.

We recommend using astro-portabletext to render your PortableText fields in Astro. See an example of this in apps/example/src/components/PortableText.astro, including using custom components to render custom blocks and annotations.

---
import {PortableText as PortableTextInternal} from "astro-portabletext"
import CallToActionBox from "./CallToActionBox.astro";
import Code from "./Code.astro";
import SanityImage from "./SanityImage.astro";
import YouTube from "./YouTube.astro";
import InternalLink from "./InternalLink.astro";

const components = {
  type: {
    callToActionBox: CallToActionBox,
    code: Code,
    image: SanityImage,
    youtube: YouTube,
  },
  mark: {
    internalLink: InternalLink
  }
};

---

<PortableTextInternal value={Astro.props.value} components={components} />

Presenting images

Sanity comes with a native asset pipeline for your images and files. It has on-demand transforms, automatic optimization for browsers that supports webp, and serves images from a global CDN network. When you upload images to Sanity, it will also automatically analyze the image and add a metadata document with information like dimensions, color palette, generate blurhash, and LQIP strings.

We recommend using @sanity/image-url to help you generate URLs for presenting Sanity images in your Astro app. See an example of this in apps/example/src/components/SanityImage.astro

You can also use community-contributed integrations like astro-sanity-picture to integrate images from Sanity into your website.

Resources

• The official Astro + Sanity guide
• Sanity documentation
• Portable Text integration for Astro
• Astro Sanity Picture
• Egghead's Introduction to GROQ