BlueprintsLast updated July 29, 2026

Blueprint configuration reference

Reference documentation for the Blueprint configuration files.

Overview

Learn what Blueprints are, how they work, and how to get started.

The Blueprints configuration file (sanity.blueprint.ts) defines resources, like Functions, for deployment to Sanity's infrastructure.

Interact with Blueprints by using the npx sanity blueprints CLI command.

The top-level of the blueprint configuration file contains the following properties:

Some configuration properties, like blueprintVersion, are handled automatically when using the defineBlueprint helper.

Top-level fields

The file default-exports a call to defineBlueprint. Most files set resources and values.

Key	Type	Notes
resources	BlueprintResource[]	The resources to manage. Each entry is the output of a definer.
values	Record<string, string>	Reusable constants, referenced with $.values.<key>. Values are always strings.

Resources

The following properties are shared across all resources. Additional resource-specific properties follow in the sections below.

Blueprints works by comparing your declared resources against what's already in the Stack, matching everything by name. It has no concept of an in-place rename. When you change a name, two things happen: the new name doesn't exist yet so Blueprints creates it, and the old name is gone from your blueprint so Blueprints destroys it.

From your perspective it's one rename. From Blueprints' perspective it's two unrelated resources: one created, one destroyed. There's no internal ID linking them, so nothing carries over. For a Function, that means the deployed infrastructure gets torn down and rebuilt, execution logs and history don't migrate, and any IDs or URLs that downstream systems depend on can change. There's no automatic migration and no undo.

If you need to change a name or type, treat it as a destroy-and-recreate:

Run blueprints plan first. It's a safe, read-only preview that shows exactly what will change without touching anything.
Confirm the plan shows a destroy of the old resource and a create of the new one. That's how you know things are working as expected.
Run blueprints deploy to apply. Note that deploy doesn't show a preview on its own, so always plan first.
Expect a brief gap while the resource is replaced, and handle any state migration yourself.

If keeping the resource matters more than its name, leave the name alone.

Functions

In addition to the required common resource properties above, functions also contain the following properties.

src
string
The path, relative to the blueprint configuration file, of the individual function directory. Will be inferred from the name if omitted. For example, functions/myFunction.
type
string
Specifies the Function type. Supported Function types are:
- sanity.function.document: this Function will react to changes in your dataset documents, like when a document is created, updated or deleted.
- sanity.function.media-library.asset: this Function will react to changes in your Media Library, like when an asset is uploaded, updated or deleted. Note that your plan must have access to the Media Library to use this Function type.
- sanity.function.sync-tag-invalidate: this Function will react to changes in your Live Content. It is very similar to the document and involves calling back into Sanity. More details can be found in the our Sync Tag Invalidate Function guide.
event
object
Configuration options for the triggering event. See the event properties section below for details.
timeout
integer
The max invocation time, in seconds, of the function.
- Default: 10
- Minimum: 1
- Maximum: 900
memory
integer
Sets the max memory allocation, in GBs.
- Default: 1
- Min: 1
- Max: 10
env
object
Set environment variables for the function. The env object accepts custom keys with string values. This is an alternative approach to using the sanity functions env CLI command. Note: Setting environment variables in this manner is only additive. It can create/update variables, but in order to remove an environment variable you must use the sanity functions env remove command.
transpile
boolean
If false, you will need to transpile any TypeScript code yourself and output the results to the individual function's .build directory. Defaults to true.
autoResolveDeps
boolean
If false, disables the automatic dependency resolution. Defaults to true.

A complete list of available properties can be found in the defineDocumentFunction reference documentation.

`event` properties

on
string
Defines the types of events that trigger your Function. You can include more than one, but you cannot combine publish with other events. The options are:
- create: Activates when a document is created. Defaults to includeDrafts: false and includeAllVersions: false.
- delete: Activates when a document is deleted. Defaults to includeDrafts: false and includeAllVersions: false.
- update: Activates when a document is updated. Defaults to includeDrafts: false and includeAllVersions: false.
- publish (deprecated): Activates when a document is published. Essentially a shorthand for: create + update with includeAllVersions: true. Use explicit create/update events instead.
These actions trigger on individual documents with unique _id values.
Only applies to the following Function types:
sanity.function.document
sanity.function.media-library.asset
filter
string
A valid GROQ filter. Learn more about GROQ Filters.
Only include the contents of the filter, not any other surrounding syntax.
✅ Do this: _type == "article"
❌ Not this: [_type == "article"]
Only applies to the following Function types:
sanity.function.document
sanity.function.media-library.asset
projection
string
A valid GROQ projection. Example: {title, _id, slug}
Only applies to the following Function types:
sanity.function.document
sanity.function.media-library.asset
includeDrafts
boolean
Determines whether events on draft documents (drafts.**) trigger the function. Defaults to false. When false: draft edits are ignored; only published document changes trigger. When true: every draft edit triggers the function. Please note that turning this on can quickly have your Function hit rate limits.
Only applies to the following Function types:
- sanity.function.document
- sanity.function.media-library.asset
includeAllVersions
boolean
Determines whether events on version documents (versions.**) trigger the function. This includes documents in Content Releases and Scheduled Drafts. Defaults to false. When false: version edits are ignored; the function only triggers when versions are published. When true: every version edit triggers the function. Please note that turning this on can quickly have your Function hit rate limits.
Only applies to the following Function types:
- sanity.function.document
resource
object
Defines the resource from which changes will trigger your function. If defined, you must specify a type and id. If not set, the resource will default to all datasets for the Blueprint's linked project.
Accepted values depend on what type of Function you are defining:
- Optional if your Function type is sanity.function.document or sanity.function.sync-tag-invalidate. If not specified, will react to changes in all datasets in your function’s housing project.
  - If defined, the resource.type must be dataset and resource.id is specified in the form <projectId>.<datasetName>.
  - You can set <datasetName> to * to signify "all datasets in the project with ID <projectId>."
- Required if your Function type is sanity.function.media-library.*. The resource.type must be media-library and resource.id should equal your Media Library ID.

Example

import {
  defineBlueprint,
  defineDocumentFunction,
  defineMediaLibraryAssetFunction,
  defineSyncTagInvalidateFunction,
} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineDocumentFunction({
      name: "log-event",
      event: {
        on: ["update"],
        filter: "_type == 'post'",
        projection: "{title, _id, _type}",
        resource: {
          type: 'dataset',
          id: 'myProject.myDataset'
        }
      },
      env: {
        example: 'value'
      }
    }),
    // Helper introduced in @sanity/blueprints v0.4.0
    defineMediaLibraryAssetFunction({
      name: "image-title-updated",
      event: {
        on: ["update"],
        filter: "delta::changedAny(title)",
        projection: "{title, _id, versions}",
        resource: {
          type: 'media-library',
          id: 'mlAbcd1234'
        }
      }
    }),
    // Helper introduced in @sanity/blueprints v0.15.0
    defineSyncTagInvalidateFunction({
      name: "invalidate-cache",
      event: {
        resource: {
          type: 'dataset',
          id: 'myProjectId.myProductionDataset'
        }
      }
    })
  ]
})

import {
  defineBlueprint,
  defineDocumentFunction,
  defineMediaLibraryAssetFunction,
  defineSyncTagInvalidateFunction,
} from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineDocumentFunction({
      name: "log-event",
      event: {
        on: ["update"],
        filter: "_type == 'post'",
        projection: "{title, _id, _type}",
        resource: {
          type: 'dataset',
          id: 'myProject.myDataset'
        }
      },
      env: {
        example: 'value'
      }
    }),
    // Helper introduced in @sanity/blueprints v0.4.0
    defineMediaLibraryAssetFunction({
      name: "image-title-updated",
      event: {
        on: ["update"],
        filter: "delta::changedAny(title)",
        projection: "{title, _id, versions}",
        resource: {
          type: 'media-library',
          id: 'mlAbcd1234'
        }
      }
    }),
    // Helper introduced in @sanity/blueprints v0.15.0
    defineSyncTagInvalidateFunction({
      name: "invalidate-cache",
      event: {
        resource: {
          type: 'dataset',
          id: 'myProjectId.myProductionDataset'
        }
      }
    })
  ]
})

{
  "blueprintVersion": "2024-10-01",
  "resources": [
    {
      "name": "log-event",
      "src": "functions/log-event",
      "type": "sanity.function.document",
      "event": {
        "on": [
          "update"
        ],
        "filter": "_type == 'post'",
        "projection": "{title, _id, _type}",
        "resource": {
          "type": "dataset",
          "id": "myProject.myDataset"
        }
      },
      "env": {
        "example": "value"
      }
    },
    {
      "name": "image-created",
      "src": "functions/image-created",
      "type": "sanity.function.media-library.asset",
      "event": {
        "on": [
          "create"
        ],
        "filter": "assetType == 'sanity.imageAsset'",
        "projection": "{title, _id, versions}",
        "resource": {
          "type": "media-library",
          "id": "mlAbcd1234"
        }
      }
    }
  ]
}

{
  "blueprintVersion": "2024-10-01",
  "resources": [
    {
      "name": "log-event",
      "src": "functions/log-event",
      "type": "sanity.function.document",
      "event": {
        "on": [
          "update"
        ],
        "filter": "_type == 'post'",
        "projection": "{title, _id, _type}",
        "resource": {
          "type": "dataset",
          "id": "myProject.myDataset"
        }
      },
      "env": {
        "example": "value"
      }
    },
    {
      "name": "image-created",
      "src": "functions/image-created",
      "type": "sanity.function.media-library.asset",
      "event": {
        "on": [
          "create"
        ],
        "filter": "assetType == 'sanity.imageAsset'",
        "projection": "{title, _id, versions}",
        "resource": {
          "type": "media-library",
          "id": "mlAbcd1234"
        }
      }
    }
  ]
}

Additional resources

Reference documentation for additional Blueprint resources is available in the @sanity/blueprints documentation.

Common resource fields

Every resource has a unique name and an optional lifecycle. You set name; the definer sets the resource's type for you, so you rarely write it directly. The name is unique within the Stack and is the resource's identity for matching.

The lifecycle field

lifecycle.deletionPolicy controls what happens to a resource when it's removed from the file or the Stack is destroyed:

Policy	On a normal deploy	Removed from the file	On destroy
allow	Updated in place	Destroyed	Destroyed
retain	Updated in place	Deploy fails	Kept (detached)
replace	Destroyed and recreated	Destroyed	Destroyed
protect	Skipped	Deploy fails	Deploy fails

Stateless resources default to allow; stateful resources such as datasets default to retain. lifecycle.ownershipAction covers attaching, detaching, and cross-stack references, and lifecycle.dependsOn orders deployments when there is no parameter reference between resources.

defineDataset({
  name: 'production',
  project: '$.values.projectId',
  lifecycle: { deletionPolicy: 'retain' },
})

defineDataset({
  name: 'production',
  project: '$.values.projectId',
  lifecycle: { deletionPolicy: 'retain' },
})

Reference syntax

Resources refer to constants and to each other with a small $ syntax, passed as a plain string:

Syntax	Meaning
$.values.<key>	A value from the values block, resolved when the file runs.
$.resources.<name>	Another resource in the file. Creates a dependency edge.
$.resources.<name>.id	The generated ID of another resource, usable as a string.

TypeScript / JavaScript helpers

You can configure Blueprints with TypeScript and JavaScript. If you select either during sanity blueprints init, the CLI prompts you to install the @sanity/blueprints package. You can also add it to an existing project by adding it to your Blueprints-level project directory.

The helpers provide defaults and allow you to omit some configuration options. You can always override these defaults by explicitly setting the values as you would with the JSON format.

Blueprint configuration reference

Overview

RequiredblueprintVersion

Requiredresources

Top-level fields

Automatic fields

Resources

Requiredname

Requiredtype

There's no such thing as a rename.

Changing a resource's type under the same name does the same thing.

Functions

src

type

event

timeout

memory

env

transpile

autoResolveDeps

`event` properties

on

filter

projection

includeDrafts

includeAllVersions

resource

Example

Additional resources

Common resource fields

The lifecycle field

Reference syntax

TypeScript / JavaScript helpers

Define a custom role

Blueprints glossary

Overview

RequiredblueprintVersion

Requiredresources

Top-level fields

Automatic fields

Resources

Requiredname

Requiredtype

There's no such thing as a rename.

Changing a resource's type under the same name does the same thing.

Functions

event properties

Example

Additional resources

Common resource fields

The lifecycle field

Reference syntax

TypeScript / JavaScript helpers

Define a custom role

Blueprints glossary

`event` properties