Reference a resource across stacks

Learn how to read values from a resource managed by another Blueprints stack without taking ownership of it.

If a resource in one stack needs values from a resource in another stack, you can reference it. Blueprints reads the referenced resource during deployment but does not manage or modify it.

The referenced resource must be in a stack scoped to the same project or organization as the current stack.

• The name or ID of the stack that manages the resource you want to reference.
• An existing blueprint attached to the same scope as the other stack. See Blueprints introduction if you haven't set one up yet.
• The name of the resource in that stack.
• Read permissions on the target resource. Blueprints checks read permissions during deployment and the deploy will fail if you do not have access.

Add the resource to your blueprint with the reference* helpers, then use it in another resource via a $.resources.* path.

In this example, a robot token (deploy-robot) managed by a shared stack (shared-infrastructure) is referenced with the referenceRobotToken helper and used to authenticate a document function.

import { defineBlueprint, referenceRobotToken, defineDocumentFunction } from "@sanity/blueprints"

export default defineBlueprint({
  resources: [
    referenceRobotToken({
      name: 'deploy-robot',
      stack: 'shared-infrastructure',
    }),

    defineDocumentFunction({
      name: 'sync-content',
      src: 'functions/sync-content',
      robotToken: '$.resources.deploy-robot',
      event: {
        on: ['create', 'update'],
        filter: "_type == 'article'",
      },
    }),
  ],
})

The stack field is the name or ID of the stack that owns the resource. The name field is the name of the resource in that stack.

Using $.resources.deploy-robot in the function's robotToken field creates an implicit deployment dependency. Blueprints resolves the referenced token before deploying the function.

Reference helpers, such as referenceRole and referenceRobotToken are available where appropriate in the @sanity/blueprints package.

Once you've configured the reference, deploy the blueprint.

npx sanity blueprints deploy

pnpm dlx sanity blueprints deploy

yarn dlx sanity blueprints deploy

bunx sanity blueprints deploy

During the deploy, Blueprints reads the referenced resource and makes its properties available to other resources in the stack. It does not modify the resource or change its ownership.

The deploy will fail if the target stack does not exist, has a different scope, or the named resource is not found in that stack. Check that the stack and name values are correct before deploying.