> For AI agents: the complete Sanity documentation index is available at [https://www.sanity.io/docs/llms.txt](https://www.sanity.io/docs/llms.txt).

# Blueprint configuration reference

Reference documentation for the Blueprint configuration files.

[Overview](https://www.sanity.io/docs/blueprints/blueprints-introduction)
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](https://www.sanity.io/docs/cli-reference/cli-blueprints).

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

#### Properties

**blueprintVersion** (string, required)

Defines the version of the Blueprints specification to use when parsing the configuration. Uses the YYYY-MM-DD format.

**resources** (array, required)

An array of Sanity resources, such as Functions, CORS origins, webhooks, roles, and robot tokens.

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`.

##### Top-level fields

| Key | Type | Notes |
| --- | --- | --- |
| resources | BlueprintResource[] | The resources to manage. Each entry is the output of a definer. |
| values | Record<string, string \| number> | Reusable constants, referenced with $.values.<key>. Values must be strings or numbers. |

> [!NOTE]
> Automatic fields
> `defineBlueprint` also sets `blueprintVersion` and `$schema` for you, so you don't write them. They matter only if you hand-author a `sanity.blueprint.json` file instead of using `defineBlueprint`.

## Resources

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

#### Properties

**name** (string, required)

A unique resource name. Must be an alphanumeric string that can contain dashes or underscores.

**type** (string, required)

A resource type. For Sanity resources, this is made up of the sanity namespace, category, subcategory, and resource types separated by single periods. For example: sanity.function.document or sanity.function.media-library.asset.

> [!WARNING]
> There's no such thing as a rename.
> Changing a resource's name deletes the old resource and creates a new one.

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.

> [!WARNING]
> Changing a resource's type under the same name does the same thing.
> Resources are matched only by name. If the name matches but the type differs, Blueprints replaces the resource by destroying the old one and creating a new one.

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

1. Run `blueprints plan` first. It's a safe, read-only preview that shows exactly what will change without touching anything.
2. 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.
3. Run `blueprints deploy` to apply. Note that `deploy` doesn't show a preview on its own, so always plan first.
4. 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](https://www.sanity.io/docs/blueprints/blueprint-config) above, functions also contain the following properties.

#### 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 reacts to changes in your dataset documents, like when a document is created, updated, or deleted.

sanity.function.media-library.asset: this Function reacts to changes in your Media Library, like when an asset is uploaded, updated, or deleted. Your plan must have access to the Media Library to use this Function type. 

sanity.function.sync-tag-invalidate: this Function reacts to changes in your Live Content. It is very similar to the document type and involves calling back into Sanity. For more details, see Create a Sync Tag Invalidate Function.

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

Minimum: 1

Maximum: 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](https://reference.sanity.io/_sanity/blueprints/index/defineDocumentFunction/).

#### `event` properties

#### Properties

**on** (array)

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. Turning this on can quickly make 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. Turning this on can quickly make 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

**sanity.blueprint.ts (TypeScript / JavaScript)**

```typescript
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'
        }
      }
    })
  ]
})

```

**sanity.blueprint.json (JSON)**

```json
{
  "$schema": "https://schemas.sanity.io/blueprints/v2024-10-01/blueprint.schema.json",
  "blueprintVersion": "2024-10-01",
  "resources": [
    {
      "type": "sanity.function.document",
      "name": "log-event",
      "src": "functions/log-event",
      "env": {
        "example": "value"
      },
      "event": {
        "on": [
          "update"
        ],
        "filter": "_type == 'post'",
        "projection": "{title, _id, _type}",
        "resource": {
          "type": "dataset",
          "id": "myProject.myDataset"
        }
      }
    },
    {
      "type": "sanity.function.media-library.asset",
      "name": "image-title-updated",
      "src": "functions/image-title-updated",
      "event": {
        "on": [
          "update"
        ],
        "filter": "delta::changedAny(title)",
        "projection": "{title, _id, versions}",
        "resource": {
          "type": "media-library",
          "id": "mlAbcd1234"
        }
      }
    },
    {
      "type": "sanity.function.sync-tag-invalidate",
      "name": "invalidate-cache",
      "src": "functions/invalidate-cache",
      "event": {
        "resource": {
          "type": "dataset",
          "id": "myProjectId.myProductionDataset"
        }
      }
    }
  ]
}
```

### Additional resources

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

- [CORS reference](https://reference.sanity.io/_sanity/blueprints/index/defineCorsOrigin/)
- [Webhooks reference](https://reference.sanity.io/_sanity/blueprints/index/defineDocumentWebhook/)
- [Media Library Asset Function reference](https://reference.sanity.io/_sanity/blueprints/index/defineMediaLibraryAssetFunction/)
- [Robot token reference](https://reference.sanity.io/_sanity/blueprints/index/defineRobotToken/)
- [Role reference](https://reference.sanity.io/_sanity/blueprints/index/defineRole/)

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

##### Deletion policies

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

**sanity.blueprint.ts**

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

##### Reference syntax

| Syntax | Meaning |
| --- | --- |
| $.values.<key> | A value from the values block, substituted when Blueprints parses the blueprint. |
| $.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](https://github.com/sanity-io/blueprints-node) package. You can also add it to an existing project by adding it to your Blueprints-level project directory.

**NPM**

```sh
npm i @sanity/blueprints
```

**PNPM**

```sh
pnpm add @sanity/blueprints
```

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.



## Related changelog entries

Entries are listed newest first; each link points to the full entry as markdown. Follow one when you need to know what changed, when, or why — for example, to summarize recent updates, explain behavior that differs from older documentation, or check whether a fix has shipped.

- [Sanity Studio v4.21.0: Configure Sanity MCP server with CLI, updated blueprint commands + improvements and bugfixes](https://www.sanity.io/docs/changelog/beb93f6c-7913-4ea7-8bbb-847ba7b51b19.md) — December 9, 2025
- [Functions v2025-11-06: New Function Type: Media Library Asset Functions](https://www.sanity.io/docs/changelog/d3002427-6ac1-4711-b534-20d1c67a9777.md) — November 6, 2025
- [Functions v2025-09-22: Introducing Functions dataset scoping](https://www.sanity.io/docs/changelog/b3c69b01-001b-496e-955d-a30517bb6ce1.md) — September 22, 2025
- [Functions v2025-08-20: Functions new document change events and filtering options!](https://www.sanity.io/docs/changelog/15c41ae1-ac85-45c1-a5fe-81ff8da878ad.md) — August 20, 2025
- [Functions v2025-08-06: Functions `projection` breaking change](https://www.sanity.io/docs/changelog/20d80d7f-c3fe-44ae-8d53-61424824dadd.md) — August 6, 2025
- [Sanity Studio v3.92.0: Faster dev server, Portable Text plugins, new Blueprints syntax, and more improvements](https://www.sanity.io/docs/changelog/90aaa078-3114-4db6-9cd3-b80a11bced1b.md) — June 10, 2025