SpecificationsLast updated November 20, 2025

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

Resources

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

Functions

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

srcstring
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.
typestring
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.
eventobject
Configuration options for the triggering event. See the event properties section below for details.
timeoutinteger
The max invocation time, in seconds, of the function.
- Default: 10
- Minimum: 1
- Maximum: 900
memoryinteger
Sets the max memory allocation, in GBs.
- Default: 1
- Min: 1
- Max: 10
envobject
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.
transpileboolean
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.
autoResolveDepsboolean
If false, disables the automatic dependency resolution. Defaults to true.

`event` properties

onstring
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: Activates when a document is published. Essentially a shorthand for: create + update. Defaults to includeDrafts: false and includeAllVersions: true.
These actions trigger on individual documents with unique _id values.
filterstring
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"]
projectionstring
A valid GROQ projection. Example: {title, _id, slug}
includeDraftsboolean
Determines whether the event trigger should take into account events happening on draft documents. Defaults to false. Please note that turning this on by setting it to true can quickly have your Function hit rate limits.
Only applies to the following Function types:
- sanity.function.document
- sanity.function.media-library.asset
includeAllVersionsboolean
Determines whether the event trigger should take into account events happening on version documents (documents that are part of Content Releases). Defaults to false. Please note that turning this on by setting it to true can quickly have your Function hit rate limits.
Only applies to the following Function types:
- sanity.function.document
resourceobject
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.
  - 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} 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'
        }
      }
    })
  ]
})

import {defineBlueprint, defineDocumentFunction, defineMediaLibraryAssetFunction} 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'
        }
      }
    })
  ]
})

{
  "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"
        }
      }
    }
  ]
}

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.

Handler reference

Was this page helpful?

Blueprint configuration reference

Overview

RequiredblueprintVersionstring

Requiredresourcesarray

Resources

Requirednamestring

Requiredtypestring

Functions

srcstring

typestring

eventobject

timeoutinteger

memoryinteger

envobject

transpileboolean

autoResolveDepsboolean

`event` properties

onstring

filterstring

projectionstring

includeDraftsboolean

includeAllVersionsboolean

resourceobject

Example

TypeScript / JavaScript helpers

Handler reference

Overview

RequiredblueprintVersionstring

Requiredresourcesarray

Resources

Requirednamestring

Requiredtypestring

Functions

srcstring

typestring

eventobject

timeoutinteger

memoryinteger

envobject

transpileboolean

autoResolveDepsboolean

event properties

onstring

filterstring

projectionstring

includeDraftsboolean

includeAllVersionsboolean

resourceobject

Example

TypeScript / JavaScript helpers

Handler reference

`event` properties