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.

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

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

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.

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.

You can scope stacks to a project or to an organization. For how scope affects resources and how promotion works, see 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, require an organization-scoped stack.

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:

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.

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.

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:

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

✅ Instead, do this:

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

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.