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

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

**sanity.blueprint.ts**

```typescript
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:

**npm**

```shell
npx sanity@latest blueprints init .
```

**pnpm**

```shell
pnpm dlx sanity@latest blueprints init .
```

**yarn**

```shell
yarn dlx sanity@latest blueprints init .
```

**bun**

```shell
bunx sanity@latest blueprints init .
```

## Deploy each environment

Pass the environment variable and the matching `--stack` on the same command:

**CLI**

```sh
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:

**npm**

```shell
npx sanity@latest blueprints stacks
```

**pnpm**

```shell
pnpm dlx sanity@latest blueprints stacks
```

**yarn**

```shell
yarn dlx sanity@latest blueprints stacks
```

**bun**

```shell
bunx sanity@latest blueprints stacks
```

## How targeting works

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

> [!WARNING]
> --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.

> [!NOTE]
> 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.

#### Related

[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.

[Deploy Blueprints from CI](https://www.sanity.io/docs/blueprints/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](https://www.sanity.io/docs/cli-reference/cli-blueprints)
Reference documentation for the Sanity CLI Blueprints command.