Blueprints introduction

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

Blueprints enable 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 blueprints init, points at a stack, and deploys.

• The latest version of Sanity CLI (sanity@latest) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with npx sanity@latest.
• Permissions:
  • Project-scoped blueprints require an admin role within the project, or a role or robot token with the sanity.project.blueprints.deploy permission.
  • Organization-scoped blueprints require an admin role, 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 Blueprints.

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

For example, marketing 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

You can scope stacks to a project (the default) or to an organization.

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

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. It checks your input as you write it, so mistakes surface in your editor instead of at deploy time. 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 string constants, referenced with $.values.<key>. The example reads the project ID from the environment, so the file carries no hard-coded IDs.

Projects have a limit of 3 stacks. If you reach your limit and want to remove a stack, see the Remove a stack steps below.

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

If you're unsure which stacks are deployed, run the blueprints stacks command.

npx sanity@latest blueprints stacks

pnpm dlx sanity@latest blueprints stacks

yarn dlx sanity@latest blueprints stacks

bunx sanity@latest blueprints stacks

To view the currently selected stack, run the blueprints info command.

npx sanity@latest blueprints info

pnpm dlx sanity@latest blueprints info

yarn dlx sanity@latest blueprints info

bunx sanity@latest blueprints info

To remove a deployed stack, run the following commands from a directory containing a configured blueprint for the same project as the stack you want to delete.

First, retrieve the stack identifier (it starts with ST-):

npx sanity@latest blueprints info

pnpm dlx sanity@latest blueprints info

yarn dlx sanity@latest blueprints info

bunx sanity@latest blueprints info

Next, run the following command with the stack identifier from the previous step.

blueprints destroy --stack-id <ST-someid>