> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# 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`.

## Configure Studio embedding

### 1. Add studioBasePath to your integration config

**astro.config.mjs**

```typescript
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(),
  ],
})
```

### 2. Create a Studio configuration file

**sanity.config.ts**

```typescript
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
    ],
  },
})
```

### 3. Configure CORS

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, select **API › CORS origins** in the sidebar, and 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.

## Known issues

### Page refresh returns 404

With browser history routing, Studio sub-routes like `/admin/structure` only exist within the Studio's client-side router, so the server has to answer for every path under the base path. The integration handles this with a server-rendered catch-all route, which needs a server adapter. With hash routing, the default for `output: 'static'`, the Studio is a single prerendered page at `/admin` and Studio navigation stays in the URL hash, so refreshing the page doesn't request a sub-route from the server. In both cases, you don't need to add rewrite rules on your hosting platform.

## Multiple workspaces

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.

## Router modes

The embedded Studio's default router depends on Astro's `output` setting: hash routing when `output` is `'static'`, and browser history routing otherwise. With 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.

With hash-based routing, Studio navigation stays within a single URL like `/admin#/structure/post;abc123`. To choose a router explicitly, set `studioRouterHistory` to `'hash'` or `'browser'` in your integration options. Hash routing can be useful on a server-rendered site if your hosting platform has difficulty with the catch-all route pattern.

**astro.config.mjs**

```javascript
// 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
})
```

### Hot module replacement disruptions

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.

## Separating Studio and frontend concerns

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.

