The resource graph

How resources reference each other with the $ syntax, and why a blueprint file is a connected system.

Inside a blueprint file you address other values with a small $ syntax, passed as a plain string. There are two forms you'll use most:

A value is always a string (not an object or array). Define it once in the values block and reference it with $.values.<key> wherever it's needed. The most common use is a project ID drawn from the environment, so the file carries no hard-coded IDs:

import { defineBlueprint, defineCorsOrigin, defineDocumentWebhook } from '@sanity/blueprints'

export default defineBlueprint({
  values: {
    projectId: process.env.PROJECT_ID,
  },
  resources: [
    defineCorsOrigin({
      name: 'studio-cors',
      project: '$.values.projectId',
      origin: 'https://my-studio.sanity.studio',
      allowCredentials: true,
    }),
    defineDocumentWebhook({
      name: 'revalidate',
      project: '$.values.projectId',
      dataset: 'production',
      apiVersion: 'v2025-02-19',
      url: 'https://example.com/api/revalidate',
      on: ['create', 'update', 'delete'],
    }),
  ],
})

Values resolve when the file runs, so they can't be built from things that only exist at deploy time. If you need to compose a string, do it in plain JavaScript at the top of the file and assign the result to a value.

When one resource names another with $.resources.<name>, Blueprints records a dependency: the referenced resource is resolved before the resource that points at it. A robot token that uses a role defined in the same file is a clear example:

import { defineBlueprint, defineRole, defineRobotToken } from '@sanity/blueprints'

export default defineBlueprint({
  values: {
    projectId: process.env.PROJECT_ID,
  },
  resources: [
    defineRole({
      name: 'ci-deploy-role',
      title: 'CI Deploy Role',
      appliesToUsers: false,
      appliesToRobots: true,
      permissions: [{ name: 'sanity-project-cors', action: 'create' }],
    }),
    defineRobotToken({
      name: 'ci-robot',
      memberships: [
        {
          resourceType: 'project',
          resourceId: '$.values.projectId',
          // references the role above, so it's created first
          roleNames: ['$.resources.ci-deploy-role'],
        },
      ],
    }),
  ],
})

You don't order resources yourself. Blueprints reads the references, builds the graph, and arranges the work so each dependency exists before it's needed.

The graph is what makes a blueprint file more than a pile of settings. It records how your resources relate (this token uses that role, this webhook watches that dataset) and makes those relationships explicit, reviewable, and reproducible. Change one resource and the connected ones come along with it.

A resource in one stack can hold a read-only reference to a resource in another stack in the same scope. This is an advanced, evolving capability. For the common case of pointing resources at an existing project, define the project ID as a value and supply it from the environment, as shown above.