> 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).

# Blueprints introduction

Learn what Blueprints are, how they work, and how to get started.

Blueprints enables infrastructure-as-code level management of Sanity resources.

Blueprints replaces one-off changes in the web interface with a **declarative** workflow. You describe the resources you want in one file, the **blueprint file** (`sanity.blueprint.ts`, sometimes called the manifest), and keep it in your repository alongside your application code. When you deploy, Sanity compares the file against what already exists and makes reality match it. If it's not in the blueprint, it's not deployed: the file is the source of truth.

Managing resources this way has a few compounding benefits:

- **Auditable:** Your setup lives in version control next to your code. Changes go through pull requests and have a history.
- **Reproducible:** Create staging or per-developer environments from the same file, so environments stay consistent instead of drifting apart.
- **Deterministic:** A plan shows the exact changes before you apply them.
- **Faster onboarding:** A teammate runs `sanity blueprints init`, points at a stack, and deploys.

#### Get started

[Your first Blueprint](https://www.sanity.io/docs/blueprints/your-first-blueprint)
Set up a blueprint, run a plan, and deploy your first resource (a CORS origin) to a real Sanity stack.

## Requirements

- We recommend the latest version of the Sanity CLI (`sanity@latest`) for working with Blueprints and Functions. You can always run the latest CLI commands with `npx sanity@latest`.
- Permissions:- Project-scoped stacks require the Administrator, Developer, or Blueprints Deployer role in the project, or another role or robot token with the `sanity.project.blueprints.deploy` permission. For CI, use a robot token with the Blueprints Deployer role.
- Organization-scoped stacks require the Administrator role in the organization, or an organization robot token with the `sanity.blueprints.deploy` permission.



## Core concepts

### Blueprint

Like a configuration file, a blueprint lets you define and customize Sanity resources.

[Blueprint configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.

### Resource

Core Sanity components are resources. You can create and update resources by defining them in a blueprint. Resources range from infrastructure like datasets and functions to applications and singleton configs such as Media Library.

#### Define resources with Blueprints

[Functions](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.

[Define a webhook with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-webhook)
Blueprints let you define and manage your webhooks in code, then deploy them in a predictable manner.

[Define a CORS origin with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-cors)
Blueprints allow you to define and manage your CORS origins in code, then deploy them in a predictable manner. 

[Define a robot token with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-robot-tokens)
Blueprints let you create robot tokens alongside other resources for use in the blueprint.

[Define a role with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-role)
Use Blueprints to define a custom role in code alongside your project's other resources.

### Stack

```mermaid
flowchart LR
    subgraph local["Local workspace (desired state, git)"]
        bp["sanity.blueprint.ts<br/>declares resources"]
        fn["functions/ handlers"]
    end

    subgraph infra["Sanity infrastructure (actual state)"]
        subgraph stack["Stack (ST-xxxx): managed as one unit"]
            res["Functions · webhooks · CORS<br/>tokens · roles · datasets<br/>scope: project or org"]
        end
        subgraph outside["Outside the stack: not in any blueprint"]
            unmanaged["Manage UI · other stacks<br/>untracked, untouched"]
        end
    end

    bp -->|"plan: diff, matched by name"| stack
    bp -->|"deploy: apply changes"| stack
```

A stack is a collection of resources that are managed as a single unit. Stacks are linked to a project or an organization and can be multiple deployments of the same `sanity.blueprint.ts` configuration, or deployments for different blueprint configurations entirely.

For example, the marketing team might have a `sanity.blueprint.ts` that defines resources deployed to the `marketing` stack, while the commerce team may have their own `sanity.blueprint.ts` that deploys resources to the `commerce` stack.

You can view stacks with the `sanity blueprints stacks` command, and switch stacks by running `sanity blueprints init` or `sanity blueprints config --edit` in an existing blueprints project. To list, inspect, and remove stacks, see [Manage stacks](https://www.sanity.io/docs/blueprints/manage-stacks).

#### Stack scopes

You can scope stacks to a project or to an organization. For how scope affects resources and how promotion works, see [Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope).

- For project-scoped stacks, all resources default to the stack’s project. 
- For organization-scoped stacks, you must explicitly set a resource’s project (when applicable) as part of the resource’s blueprint configuration, unless the stack has a default project. A stack promoted from project scope gets a default project, so its resources that don't name a project keep resolving to it.

Some resources, like [Scheduled Functions](https://www.sanity.io/docs/functions/scheduled-function-quickstart), require an organization-scoped stack.

### Definer

A definer is a typed function such as `defineCorsOrigin` or `defineRole` that you call to declare a resource. Its types flag mistakes in your editor, and it validates values when the CLI loads the file, before anything is deployed. A blueprint file is a list of resources, each created with a definer:

**sanity.blueprint.ts**

```typescript
import { defineBlueprint, defineCorsOrigin } from '@sanity/blueprints'

export default defineBlueprint({
  values: {
    projectId: process.env.PROJECT_ID,
  },
  resources: [
    defineCorsOrigin({
      name: 'studio-cors',
      project: '$.values.projectId',
      origin: 'https://my-studio.sanity.studio',
      allowCredentials: true,
    }),
  ],
})
```

The `values` block holds reusable constants (strings or numbers), referenced with `$.values.KEY_NAME`. The example reads the project ID from the environment, so the file carries no hard-coded IDs.

> [!NOTE]
> Make changes in the blueprint file
> Blueprints manages the resources it knows about. If you change a Blueprint-managed resource in another Sanity interface, Blueprints won't see the change until the next `plan` shows the difference. Treat the blueprint file as the source of truth.

## Limitations

### Stack limit

By default, each project or organization can have up to 10 stacks. To free a slot, remove a stack you no longer use. See [Manage stacks](https://www.sanity.io/docs/blueprints/manage-stacks).

### No nested blueprints

When creating multiple blueprints in a single project, you cannot nest blueprints in subdirectories of a directory containing a `sanity.blueprint.ts` file.

❌ For example, don't do this:

**Don't do this**

```text
.
└── some-project/
    ├── sanity.blueprint.ts
    └── another-project/
        └── sanity.blueprint.ts
```

✅ Instead, do this:

**Do this**

```text
.
├── some-project/
│   └── sanity.blueprint.ts
└── another-project/
    └── sanity.blueprint.ts
```

### Applications

Applications and singleton configs are deployable as blueprint resources. A few adjacent capabilities are out of scope for now:

- There's no whole-blueprint local dev flow. Applications keep their existing local development flow.
- Blueprints references existing Media Library, Canvas, and Dashboard resources; it doesn't create them.
- Creating a schema resource is handled by a separate initiative.



## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Blueprints v2026-05-07: Organization-scoped blueprint stacks](https://www.sanity.io/docs/changelog/de50d2ce-d2fe-4c1c-9548-1fb4360845e8.md) — May 7, 2026
- [Sanity Studio v5.13.0: Grid layout for primitive arrays, new blueprints plan preview, and improved Studio validation and media handling](https://www.sanity.io/docs/changelog/studio-NS4xMi4w.md) — March 3, 2026
- [Sanity Studio v4.21.0: Configure Sanity MCP server with CLI, updated blueprint commands + improvements and bugfixes](https://www.sanity.io/docs/changelog/beb93f6c-7913-4ea7-8bbb-847ba7b51b19.md) — December 9, 2025