Manage environments with Blueprints
Deploy one blueprint file to staging, production, and other stacks.
The pattern
Keep one blueprint file. Read an environment variable inside it to select per-environment configuration, then deploy each stack with the environment variable and the --stack flag traveling together. The file stays the source of truth; the variable picks which values to apply.
import { defineBlueprint, defineCorsOrigin } from '@sanity/blueprints'
const env = process.env.SANITY_ENV ?? 'production'
const config = {
staging: { origin: 'https://staging.example.com' },
production: { origin: 'https://www.example.com' },
}[env]
export default defineBlueprint({
values: {
projectId: process.env.PROJECT_ID,
},
resources: [
defineCorsOrigin({
name: 'web-cors',
project: '$.values.projectId',
origin: config.origin,
allowCredentials: false,
}),
],
})Add a second stack
Re-run init in the existing directory. It detects the existing blueprint file, skips scaffolding, and goes straight to configuration so you can create or select a stack. Pass . to target the current directory directly:
npx sanity@latest blueprints init .
pnpm dlx sanity@latest blueprints init .
yarn dlx sanity@latest blueprints init .
bunx sanity@latest blueprints init .
Deploy each environment
Pass the environment variable and the matching --stack on the same command:
SANITY_ENV=staging npx sanity@latest blueprints deploy --stack staging SANITY_ENV=production npx sanity@latest blueprints deploy --stack production
List your stacks at any time:
npx sanity@latest blueprints stacks
pnpm dlx sanity@latest blueprints stacks
yarn dlx sanity@latest blueprints stacks
bunx sanity@latest blueprints stacks
How targeting works
| Mechanism | What it does |
|---|---|
| --stack <name-or-id> | Selects which deployed stack to act on. Available on deploy, plan, info, and logs. |
| SANITY_ENV | A convention read by your file, not by the CLI. Name it whatever you like; the example above reads it to pick config. |
--stack never creates a stack
--stack does not create a stack on a miss. It fails and points you to create one with init (or the interactive config --edit). This is deliberate, so CI cannot accidentally provision stacks.
Environment files are not auto-loaded
The CLI does not auto-load .env files. Pass environment variables explicitly on the command, as shown above.
Other ways to split stacks
Staging and production are the most common reason to run multiple stacks, but not the only one. The same one-file, many-stacks pattern applies when you split by:
- Content division: one stack per brand or property (
artist-1,artist-2). - Business area:
marketing,sales. - Region: a stack per locale or data region.
Pick the dimension that matches how your team is organized, and select it with --stack the same way.
Stacks and scope
How one blueprint file maps to many stacks, and what project versus organization scope means.
Deploy Blueprints from CI
How to deploy your Blueprint automatically from any CI system using a deploy token and environment variables.
Blueprints CLI command reference
Reference documentation for the Sanity CLI Blueprints command.