Stacks and scope
How one blueprint file maps to many stacks, and what project versus organization scope means.
Blueprint files and stacks
The blueprint file is what you edit. A stack is what it becomes once deployed: the live set of resources on Sanity's side. The relationship is one-to-many. A single file can deploy to several stacks, which is what makes environments straightforward: the same file produces a staging stack and a production stack, selected with the --stack flag at deploy time. See Manage environments with Blueprints.
The link between your local file and a particular stack lives in .sanity/blueprint.config.json, the blueprint config file. It records the scope and the stack. It's gitignored by default and isn't secret, so a team can commit it to share a default.
Two scopes
Every stack has a scope: project or organization. The blueprint file doesn't encode scope; the config file does. A projectId makes the stack project-scoped; an organizationId makes it organization-scoped.
| Project scope | Organization scope | |
|---|---|---|
| Boundary | One Sanity project | An entire organization |
| Resource's project | Defaults to the stack's project | Set project on each project-scoped resource |
| Org-scoped resource types | Not available | Available (for example, scheduled functions) |
Recommendation
Organization scope is the recommended path. It unlocks organization-scoped resource types and scales cleanly to multi-project setups. On an org-scoped stack, give each project-scoped resource an explicit project; the common pattern is to supply $.values.projectId from an environment variable.
Starting with project scope is completely fine, too. You can move to organization scope at any time with blueprints promote. See Promote a stack to organization scope.
Why scope matters
Some resource types only make sense above a single project. Scheduled (cron) functions, for example, need an organization-scoped stack. If a stack is project-scoped and you add an organization-scoped resource type, the deploy tells you to promote the stack first.
The scopes reference covers which resource types need which scope.
Promotion: from project to organization
blueprints promote converts a project-scoped stack to organization scope in place, so you never have to start over. It's a safe, additive change: it unlocks new capabilities without changing how your existing resources behave. Blueprints assigns the stack a default project, so project-scoped resources that don't name a project keep resolving to the project they always used.
Promotion is one-way (there's no demote), but nothing about your stack stops working. For the full steps, see Promote a stack to organization scope.
Manage environments with Blueprints
Deploy one blueprint file to staging, production, and other stacks.
Blueprints scopes reference
Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.
Promote a stack to organization scope
Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.