Blueprints introduction

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

Blueprints enable infrastructure-as-code level management of Sanity resources. At this time, Blueprints are limited to managing Functions.

• 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 the editor or above role within the project, or a 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.

⚠️ There's no such thing as a rename. Changing a resource's name deletes the old resource and creates a new one.

Blueprints works by comparing your declared resources against what's already in the Stack, matching everything by name. It has no concept of an in-place rename. When you change a name, two things happen: the new name doesn't exist yet so Blueprints creates it, and the old name is gone from your blueprint so Blueprints destroys it.

From your perspective it's one rename. From Blueprints' perspective it's two unrelated resources: one created, one destroyed. There's no internal ID linking them, so nothing carries over. For a Function, that means the deployed infrastructure gets torn down and rebuilt, execution logs and history don't migrate, and any IDs or URLs that downstream systems depend on can change. There's no automatic migration and no undo.

⚠️ Changing a resource's type under the same name does the same thing. Resources are matched only by name. If the name matches but the type differs, Blueprints replaces the resource by destroying the old one and creating a new one.

If you need to change a name or type, treat it as a destroy-and-recreate:

• Run blueprints plan first. It's a safe, read-only preview that shows exactly what will change without touching anything.
• Confirm the plan shows a destroy of the old resource and a create of the new one. That's how you know things are working as expected.
• Run blueprints deploy to apply. Note that deploy doesn't show a preview on its own, so always plan first.
• Expect a brief gap while the resource is replaced, and handle any state migration yourself.

If keeping the resource matters more than its name, leave the name alone.

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.

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>