Embedding Sanity Studio in Astro

Mount Sanity Studio as a route in your Astro application using @sanity/astro. Covers installation, configuration, CORS setup, and known issues.

The recommended approach is to deploy your Studio to Sanity, but you can also embed it inside your Astro app so your content editing environment lives alongside your frontend at a path like /admin.

import sanity from '@sanity/astro'
import react from '@astrojs/react'
import { defineConfig } from 'astro/config'

export default defineConfig({
  integrations: [
    sanity({
      projectId: 'your-project-id',
      dataset: 'production',
      apiVersion: '2026-03-01',
      useCdn: false,
      studioBasePath: '/admin',
    }),
    react(),
  ],
})

import { defineConfig } from 'sanity'
import { structureTool } from 'sanity/structure'

export default defineConfig({
  name: 'my-project',
  title: 'My Project',
  projectId: 'your-project-id',
  dataset: 'production',
  plugins: [structureTool()],
  schema: {
    types: [
      // Your content types go here
    ],
  },
})

The Studio makes authenticated API requests from the browser, so you need to allow your domain in your project's CORS settings. Go to sanity.io/manage, select your project, navigate to the API tab, and under CORS origins, add your development URL (e.g., http://localhost:4321) and your production URL. Check "Allow credentials" for each origin.

Caution: Only enable CORS with credentials on domains you control. Allowing credentials on a third-party domain could expose your project to unauthorized access.

When the Studio navigates to a sub-route like /admin/structure, that path only exists within the Studio's client-side router. Refreshing the page at that URL can return a 404. For server-rendered apps (output: 'server'), the integration handles catch-all routing automatically. For static builds, configure your hosting platform's rewrite rules to direct all requests under /admin/* to the /admin page.

If your Studio configuration defines multiple workspaces, the integration mounts them as sub-routes under your studioBasePath. A single workspace mounts at /admin. Multiple workspaces mount at /admin/workspace-one, /admin/workspace-two, and so on.

By default, the embedded Studio uses browser history routing. The Studio's internal navigation (opening documents, switching tools) updates the URL path, so a URL like /admin/structure/post;abc123 represents a specific document in the structure tool.

If you prefer hash-based routing (where Studio navigation stays within a single URL like /admin#/structure/post;abc123), you can configure this in your integration options. Hash routing can be useful if your hosting platform has difficulty with the catch-all route pattern.

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

export default defineConfig({
  integrations: [
    sanity({
      projectId: PUBLIC_SANITY_PROJECT_ID,
      dataset: PUBLIC_SANITY_DATASET,
      useCdn: false,
      apiVersion: "2025-02-19",
      stega: {
        studioUrl: "http://localhost:3333",
      },
      studioRouterHistory: "hash",
    }),
    react(),
  ],
  // ... rest of config
})

During development, file changes that trigger HMR can momentarily disrupt the Studio. If the Studio becomes unresponsive after an HMR update, a manual page refresh resolves it.

The embedded Studio shares Astro's development server (built on Vite), which means your Astro plugins and configuration affect the Studio's build process. This is usually fine, but can cause issues if an Astro plugin transforms files in ways that conflict with Studio dependencies, or if your project has strict Content Security Policy headers that block Studio scripts.

If you run into conflicts, consider deploying the Studio separately using sanity deploy or hosting it as its own application.