# Manage Sanity with code
#### Get started
[Introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
[Your first Blueprint](https://www.sanity.io/docs/blueprints/your-first-blueprint)
Set up a blueprint, run a plan, and deploy your first resource (a CORS origin) to a real Sanity stack.
[Create a Sanity Function](https://www.sanity.io/docs/functions/function-quickstart)
Use Blueprints to create a function
[Deploy Blueprints with GitHub Actions](https://www.sanity.io/docs/blueprints/blueprint-action)
Use the official action to deploy your blueprints with GitHub Actions.
#### Concepts
[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.
[The resource graph](https://www.sanity.io/docs/blueprints/resource-graph)
How resources reference each other with the $ syntax, and why a blueprint file is a connected system.
[Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments)
Deploy one blueprint file to staging, production, and other stacks.
[Errors and rollbacks](https://www.sanity.io/docs/blueprints/errors-and-rollbacks)
How Blueprints catches mistakes early and what happens when a deploy fails.
#### Reference documentation
[Configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.
[Blueprints CLI command reference](https://www.sanity.io/docs/cli-reference/cli-blueprints)
Reference documentation for the Sanity CLI Blueprints command.
[Blueprints scopes reference](https://www.sanity.io/docs/blueprints/scopes)
Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.
[Blueprints glossary](https://www.sanity.io/docs/blueprints/glossary)
Definitions of the core Blueprints terms: stacks, scopes, values, deletion policies, and more.
# Introduction
Blueprints enable infrastructure-as-code level management of Sanity resources.
Blueprints replaces one-off changes in the web interface with a **declarative** workflow. You describe the resources you want in one file, the **blueprint file** (`sanity.blueprint.ts`, sometimes called the manifest), and keep it in your repository alongside your application code. When you deploy, Sanity compares the file against what already exists and makes reality match it. If it's not in the blueprint, it's not deployed: the file is the source of truth.
Managing resources this way has a few compounding benefits:
- **Auditable.** Your setup lives in version control next to your code. Changes go through pull requests and have a history.
- **Reproducible.** Create staging or per-developer environments from the same file, so environments stay consistent instead of drifting apart.
- **Deterministic.** A plan shows the exact changes before you apply them.
- **Faster onboarding.** A teammate runs `blueprints init`, points at a stack, and deploys.
## Requirements
- The latest version of Sanity CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Permissions:- Project-scoped blueprints require an admin role within the project, or a role or robot token with the `sanity.project.blueprints.deploy` permission.
- Organization-scoped blueprints require an admin role, or an organization robot token with the `sanity.blueprints.deploy` permission.
## Core concepts
### Blueprint
Like a configuration file, a blueprint lets you define and customize Sanity resources.
[Blueprint configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.
### Resource
Core Sanity components are resources. You can create and update resources by defining them in Blueprints.
#### Define resources with Blueprints
[Functions](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.
[Define a webhook with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-webhook)
Blueprints allow you to define and manage your webhooks in code, then deploy them in a predictable manner.
[Define a CORS origin with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-cors)
Blueprints allow you to define and manage your CORS origins in code, then deploy them in a predictable manner.
[Define a robot token with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-robot-tokens)
Blueprints allow you to create robot tokens alongside other resources for use in the blueprint.
[Define a role with Blueprints](https://www.sanity.io/docs/blueprints/blueprints-role)
Use Blueprints to define a custom role in code alongside your project's other resources.
### Stack
Unknown block type "mermaidDiagram", specify a component for it in the `components.types` option
A stack is a collection of resources that are managed as a single unit. These are linked to a project and can be multiple deployments of the same `sanity.blueprint.ts` configuration, or deployments for different blueprint configurations entirely.
For example, marketing might have a `sanity.blueprint.ts` that defines resources deployed to the `marketing` stack, while the commerce team may have their own `sanity.blueprint.ts` that deploys resources to the `commerce` stack.
You can view stacks with the `sanity blueprints stacks` command, and switch stacks by running `sanity blueprints init` or `sanity blueprints config --edit` in an existing blueprints project
#### Stack scopes
You can scope stacks to a project (the default) or to an organization.
- For project-scoped stacks, all resources default to the stack’s project.
- For organization-scoped stacks, you must explicitly set a resource’s project (when applicable) as part of the resource’s blueprint configuration.
Some resources, like [Scheduled Functions](https://www.sanity.io/docs/functions/scheduled-function-quickstart), require an organization-scoped stack.
### Definer
A definer is a typed function such as `defineCorsOrigin` or `defineRole` that you call to declare a resource. It checks your input as you write it, so mistakes surface in your editor instead of at deploy time. A blueprint file is a list of resources, each created with a definer:
**sanity.blueprint.ts**
```typescript
import { defineBlueprint, defineCorsOrigin } 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,
}),
],
})
```
The `values` block holds reusable string constants, referenced with `$.values.`. The example reads the project ID from the environment, so the file carries no hard-coded IDs.
> [!NOTE]
> Make changes in the blueprint file
> Blueprints manages the resources it knows about. If you change a Blueprint-managed resource in another Sanity interface, Blueprints won't see the change until the next `plan` shows the difference. Treat the blueprint file as the source of truth.
## Limitations
### Stack limit
Projects have a limit of 3 stacks. If you reach your limit and want to remove a stack, see the *Remove a stack* steps below.
### No nested blueprints
When creating multiple blueprints in a single project, you cannot nest blueprints in subdirectories of a directory containing a `sanity.blueprint.ts` file.
❌ For example, don't do this:
**Don't do this**
```text
.
└── some-project/
├── sanity.blueprint.ts
└── another-project/
└── sanity.blueprint.ts
```
✅ Instead, do this:
**Do this**
```text
.
└── some-project/
| └── sanity.blueprint.ts
└── another-project/
└── sanity.blueprint.ts
```
## Troubleshooting
### View stacks for a project
If you're unsure which stacks are deployed, run the `blueprints stacks` command.
**npm**
```shell
npx sanity@latest blueprints stacks
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints stacks
```
**yarn**
```shell
yarn dlx sanity@latest blueprints stacks
```
**bun**
```shell
bunx sanity@latest blueprints stacks
```
### View current stack
To view the currently selected stack, run the `blueprints info` command.
**npm**
```shell
npx sanity@latest blueprints info
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints info
```
**yarn**
```shell
yarn dlx sanity@latest blueprints info
```
**bun**
```shell
bunx sanity@latest blueprints info
```
### Remove a stack
To remove a deployed stack, run the following commands from a directory containing a configured blueprint for the same project as the stack you want to delete.
First, retrieve the stack identifier (it starts with `ST-`):
**npm**
```shell
npx sanity@latest blueprints info
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints info
```
**yarn**
```shell
yarn dlx sanity@latest blueprints info
```
**bun**
```shell
bunx sanity@latest blueprints info
```
Next, run the following command with the stack identifier from the previous step.
**CLI**
```sh
blueprints destroy --stack-id
```
# Stacks and scope
## Blueprint files and stacks
The [blueprint file](https://www.sanity.io/docs/blueprints/blueprint-config) is what you edit. A **stack** is what it becomes once deployed: the live set of resources on Sanity's side. The relationship is one-to-many. A single file can deploy to several stacks, which is what makes environments straightforward: the same file produces a `staging` stack and a `production` stack, selected with the `--stack` flag at deploy time. See [Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments).
The link between your local file and a particular stack lives in `.sanity/blueprint.config.json`, the **blueprint config file**. It records the scope and the stack. It's gitignored by default and isn't secret, so a team can commit it to share a default.
## Two scopes
Every stack has a scope: **project** or **organization**. The blueprint file doesn't encode scope; the config file does. A `projectId` makes the stack project-scoped; an `organizationId` makes it organization-scoped.
##### Project vs organization scope
| | Project scope | Organization scope |
| --- | --- | --- |
| Boundary | One Sanity project | An entire organization |
| Resource's project | Defaults to the stack's project | Set project on each project-scoped resource |
| Org-scoped resource types | Not available | Available (for example, scheduled functions) |
> [!TIP]
> Recommendation
> Organization scope is the recommended path. It unlocks organization-scoped resource types and scales cleanly to multi-project setups. On an org-scoped stack, give each project-scoped resource an explicit `project`; the common pattern is to supply `$.values.projectId` from an environment variable.
> Starting with project scope is completely fine, too. You can move to organization scope at any time with `blueprints promote`. See [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope).
## Why scope matters
Some resource types only make sense above a single project. Scheduled (cron) functions, for example, need an organization-scoped stack. If a stack is project-scoped and you add an organization-scoped resource type, the deploy tells you to promote the stack first.
The [scopes reference](https://www.sanity.io/docs/blueprints/scopes) covers which resource types need which scope.
## Promotion: from project to organization
`blueprints promote` converts a project-scoped stack to organization scope in place, so you never have to start over. It's a safe, additive change: it unlocks new capabilities without changing how your existing resources behave. Blueprints assigns the stack a default project, so project-scoped resources that don't name a `project` keep resolving to the project they always used.
Promotion is one-way (there's no demote), but nothing about your stack stops working. For the full steps, see [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope).
#### Related
[Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments)
Deploy one blueprint file to staging, production, and other stacks.
[Blueprints scopes reference](https://www.sanity.io/docs/blueprints/scopes)
Project versus organization scope, which resource types need which scope, and how the CLI resolves scope.
[Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)
Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.
# Manage environments with Blueprints
## The pattern
Keep one blueprint file. Read an environment variable inside it to select per-environment configuration, then deploy each stack with the environment variable and the `--stack` flag traveling together. The file stays the source of truth; the variable picks which values to apply.
**sanity.blueprint.ts**
```typescript
import { defineBlueprint, defineCorsOrigin } from '@sanity/blueprints'
const env = process.env.SANITY_ENV ?? 'production'
const config = {
staging: { origin: 'https://staging.example.com' },
production: { origin: 'https://www.example.com' },
}[env]
export default defineBlueprint({
values: {
projectId: process.env.PROJECT_ID,
},
resources: [
defineCorsOrigin({
name: 'web-cors',
project: '$.values.projectId',
origin: config.origin,
allowCredentials: false,
}),
],
})
```
## Add a second stack
Re-run `init` in the existing directory. It detects the existing blueprint file, skips scaffolding, and goes straight to configuration so you can create or select a stack. Pass `.` to target the current directory directly:
**npm**
```shell
npx sanity@latest blueprints init .
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init .
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init .
```
**bun**
```shell
bunx sanity@latest blueprints init .
```
## Deploy each environment
Pass the environment variable and the matching `--stack` on the same command:
**CLI**
```sh
SANITY_ENV=staging npx sanity@latest blueprints deploy --stack staging
SANITY_ENV=production npx sanity@latest blueprints deploy --stack production
```
List your stacks at any time:
**npm**
```shell
npx sanity@latest blueprints stacks
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints stacks
```
**yarn**
```shell
yarn dlx sanity@latest blueprints stacks
```
**bun**
```shell
bunx sanity@latest blueprints stacks
```
## How targeting works
##### How targeting works
| Mechanism | What it does |
| --- | --- |
| --stack | Selects which deployed stack to act on. Available on deploy, plan, info, and logs. |
| SANITY_ENV | A convention read by your file, not by the CLI. Name it whatever you like; the example above reads it to pick config. |
> [!WARNING]
> --stack never creates a stack
> `--stack` does not create a stack on a miss. It fails and points you to create one with `init` (or the interactive `config --edit`). This is deliberate, so CI cannot accidentally provision stacks.
> [!NOTE]
> Environment files are not auto-loaded
> The CLI does not auto-load `.env` files. Pass environment variables explicitly on the command, as shown above.
## Other ways to split stacks
Staging and production are the most common reason to run multiple stacks, but not the only one. The same one-file, many-stacks pattern applies when you split by:
- **Content division**: one stack per brand or property (`artist-1`, `artist-2`).
- **Business area**: `marketing`, `sales`.
- **Region**: a stack per locale or data region.
Pick the dimension that matches how your team is organized, and select it with `--stack` the same way.
#### Related
[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.
[Deploy Blueprints from CI](https://www.sanity.io/docs/blueprints/deploy-blueprints-from-ci)
How to deploy your Blueprint automatically from any CI system using a deploy token and environment variables.
[Blueprints CLI command reference](https://www.sanity.io/docs/cli-reference/cli-blueprints)
Reference documentation for the Sanity CLI Blueprints command.
# The resource graph
## Two kinds of reference
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:
##### Reference syntax
| Syntax | Resolved | Use it for |
| --- | --- | --- |
| $.values. | When the file runs (eval time) | A reusable constant from the values block, such as a project ID. |
| $.resources. | At deploy time | A reference to another resource in the same file. This creates a dependency edge. |
| $.resources..id | At deploy time | The generated ID of another resource, usable as a string once it exists. |
## Values: constants you reuse
A value is **always a string** (not an object or array). Define it once in the `values` block and reference it with `$.values.` wherever it's needed. The most common use is a project ID drawn from the environment, so the file carries no hard-coded IDs:
**sanity.blueprint.ts**
```typescript
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.
## Resource references: edges in the graph
When one resource names another with `$.resources.`, 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:
**sanity.blueprint.ts**
```typescript
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.
> [!WARNING]
> References are validated
> A reference to a resource that doesn't exist, or a cycle where two resources depend on each other, fails validation before anything is deployed.
## Why this matters
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.
## Referencing across stacks
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.
#### Related
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
[Blueprint configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.
# Errors and rollbacks
## Most errors happen before deploy
Validation runs at more than one point, so problems surface as early as possible:
- **As you write.** The [definers](https://www.sanity.io/docs/blueprints/blueprint-config) check their input when you call them, so a missing required field or a malformed value is flagged in your editor and at build time.
- **Before applying.** When you run `plan` or `deploy`, the whole file is validated (structurally and per resource) before any change is made.
Because `plan` is read-only, running it is the safe way to surface most errors without touching anything.
## Kinds of failure
##### Kinds of failure
| Failure | What it means |
| --- | --- |
| Validation error | A resource is missing a required field, has an invalid value, or the file is structurally wrong. Caught before deploy. |
| Unresolved reference or cycle | A $.resources. points at something that doesn't exist, or two resources depend on each other. See The resource graph. |
| Scope mismatch | An organization-scoped resource type on a project-scoped stack, or a project-scoped resource with no resolvable project. See Stacks and scope. |
| Deletion-policy violation | A change would remove a resource whose deletion policy forbids it (for example a retain or protect resource). |
| Execution failure | A change passed validation but failed while being applied; for instance, an underlying service rejected it. |
Errors come back with a clear name, a human-readable message, and the path to the resource involved, so you can map the failure straight to a line in your file.
## What rollback does
If a deploy fails after some changes have already been applied, Blueprints attempts to undo the completed changes in reverse order and marks the operation as failed. The goal is to leave the stack consistent rather than half-applied.
> [!WARNING]
> Rollback is best-effort
> Rollback unwinds the actions it can, in reverse. It isn't a guaranteed atomic restore of the entire stack: some actions may not be reversible, and references to resources owned by other stacks are never touched. After a failed deploy, run `blueprints info` to see the current state, fix the cause, and deploy again.
## Reading what happened
A deploy streams its progress until the operation finishes. To review a past deploy after it has stopped tailing, including the messages from a failure, use the logs:
**npm**
```shell
# Inspect current state
npx sanity@latest blueprints info
# Re-read logs from earlier operations
npx sanity@latest blueprints logs
```
**pnpm**
```shell
# Inspect current state
pnpm dlx sanity@latest blueprints info
# Re-read logs from earlier operations
pnpm dlx sanity@latest blueprints logs
```
**yarn**
```shell
# Inspect current state
yarn dlx sanity@latest blueprints info
# Re-read logs from earlier operations
yarn dlx sanity@latest blueprints logs
```
**bun**
```shell
# Inspect current state
bunx sanity@latest blueprints info
# Re-read logs from earlier operations
bunx sanity@latest blueprints logs
```
## Recovering
1. Read the error message and the resource path it points to.
2. Fix the blueprint file (or the underlying resource, if something external changed).
3. Run `blueprints plan` to confirm the diff is now what you expect.
4. Run `blueprints deploy` again.
#### Related
[The resource graph](https://www.sanity.io/docs/blueprints/resource-graph)
How resources reference each other with the $ syntax, and why a blueprint file is a connected system.
[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.
[Blueprints CLI command reference](https://www.sanity.io/docs/cli-reference/cli-blueprints)
Reference documentation for the Sanity CLI Blueprints command.
# Your first Blueprint
You'll set up a blueprint, run a plan, and deploy your first resource (a CORS origin) to a real Sanity stack. By the end you'll have run the full edit, plan, deploy loop you use for everything else.
## Before you begin
- **Node.js and npm** installed.
- **A Sanity account, logged in.** If you're not sure, run `npx sanity@latest login`.
- **An existing Sanity project**, and its **project ID** (from the project's settings).
New to the ideas behind this? Read the [Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction) first. Otherwise, start in an empty directory.
## Step 1: Initialize a blueprint
Run `init` and follow the prompts:
**npm**
```shell
npx sanity@latest blueprints init
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init
```
**bun**
```shell
bunx sanity@latest blueprints init
```
The interactive setup walks you through a few choices:
- Confirm the directory to create the blueprint in.
- Choose your **organization** as the scope.
- Name the new stack `production`.
- Choose **TypeScript** as the format.
When it finishes, you'll have:
- `sanity.blueprint.ts`, the blueprint file you'll edit.
- `.sanity/blueprint.config.json`, which links the file to the new stack (gitignored by default).
- `@sanity/blueprints` added to your `package.json`.
## Step 2: Install dependencies
The blueprint file is real TypeScript, so install the package it imports:
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Step 3: Look at the empty stack
`init` created a stack with no resources yet. Confirm that:
**npm**
```shell
npx sanity@latest blueprints info
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints info
```
**yarn**
```shell
yarn dlx sanity@latest blueprints info
```
**bun**
```shell
bunx sanity@latest blueprints info
```
You'll see the stack you just created, with zero resources. `info` shows what's live and which stack you're connected to.
## Step 4: Declare a resource
Open `sanity.blueprint.ts` and replace its contents with the blueprint file below. It declares one CORS origin so a hosted Studio can call your project's API. Swap in your own project ID:
**sanity.blueprint.ts**
```typescript
import { defineBlueprint, defineCorsOrigin } from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineCorsOrigin({
name: 'studio-cors',
project: 'your-project-id',
origin: 'https://my-studio.sanity.studio',
allowCredentials: true,
}),
],
})
```
What you just wrote:
- `defineCorsOrigin` is a **definer**, a typed function that checks your input as you write it.
- `name` is the resource's identity in the stack.
- `project` is the project the CORS origin belongs to.
- `allowCredentials: true` lets authenticated requests through, which a Studio needs.
## Step 5: Run a plan
Before changing anything, see what a deploy would do. `plan` is read-only:
**npm**
```shell
npx sanity@latest blueprints plan
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints plan
```
**yarn**
```shell
yarn dlx sanity@latest blueprints plan
```
**bun**
```shell
bunx sanity@latest blueprints plan
```
The output shows a single **create** action for `studio-cors`. Nothing has been created yet:
**blueprints plan**
```text
Deployment Plan
+ create studio-cors sanity.project.cors
1 create
```
## Step 6: Deploy
Apply the plan:
**npm**
```shell
npx sanity@latest blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints deploy
```
**yarn**
```shell
yarn dlx sanity@latest blueprints deploy
```
**bun**
```shell
bunx sanity@latest blueprints deploy
```
`deploy` applies the change and streams progress until the stack finishes updating. When it's done, your CORS origin is live.
## Step 7: Confirm it's live
**npm**
```shell
npx sanity@latest blueprints info
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints info
```
**yarn**
```shell
yarn dlx sanity@latest blueprints info
```
**bun**
```shell
bunx sanity@latest blueprints info
```
This time `studio-cors` appears under the stack's resources. The deployed state matches your file.
> [!TIP]
> Reading past logs
> `deploy` stops tailing once it finishes. To re-read the logs of that deployment, run `npx sanity@latest blueprints logs`.
## What you did
You ran the core Blueprints loop end to end:
- Initialized a stack with `init`.
- Declared a resource in the blueprint file.
- Ran `plan` (read-only) to see the change.
- Applied it with `deploy` and confirmed with `info`.
Every future change is a variation on this loop: edit the file, plan, deploy. Ready to deploy the same file to more than one environment? See [Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments).
#### Related
[Manage environments with Blueprints](https://www.sanity.io/docs/blueprints/manage-environments)
Deploy one blueprint file to staging, production, and other stacks.
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
[Deploy Blueprints from CI](https://www.sanity.io/docs/blueprints/deploy-blueprints-from-ci)
How to deploy your Blueprint automatically from any CI system using a deploy token and environment variables.
# Project layout and monorepos
Blueprints organize Sanity infrastructure as code: projects, datasets, CORS origins, robot tokens, roles, and Functions. As your project grows, the location of `sanity.blueprint.ts` and the shape of your repository start to matter. This guide explains the three filesystem patterns we support, how dependencies behave in each, and which one to pick for a Turborepo or pnpm workspace.
Prerequisites:
- Familiarity with Blueprints and Functions.
- The latest `sanity` CLI, invoked via `npx sanity@latest` or `pnpm dlx sanity@latest`.
## The rule: lockfile and manifest live together
Your package manager's lockfile and `sanity.blueprint.ts` (the blueprint manifest) should sit in the same folder. The CLI uses the lockfile in the current working directory to detect which package manager you use. If the lockfile isn't there, the CLI defaults to npm, which fails on pnpm features like `catalog:` and `workspace:` dependencies.
In practice:
- `package-lock.json`: manifest at repo root, deploy from root.
- `yarn.lock`: manifest at repo root, deploy from root.
- `pnpm-lock.yaml`: manifest at repo root, deploy from root.
If you can't co-locate them, pass `--fn-installer pnpm` to `blueprints deploy` to force the right installer. Co-locating is the cleaner fix.
## Three filesystem patterns
### Standalone functions project
A small repository whose only purpose is to deploy Functions.
**Example structure**
```text
my-project/
├─ functions/
│ └─ log-event/
│ └─ index.ts
├─ package.json
├─ pnpm-lock.yaml
└─ sanity.blueprint.ts
```
`pnpm install` populates `node_modules` at the root. When you run `pnpm dlx sanity@latest blueprints deploy`, the CLI hydrates each Function's dependencies from that root install and packages them into an asset before uploading.
This setup is fully supported.
### Simple monorepo
Two independent directories, each with their own `package.json` and lockfile. The frontend stands on its own. Everything Sanity-related (Studio, manifest, Functions) lives together under a `sanity/` directory. No workspace tooling required.
**Example structure**
```text
my-project/
├─ frontend/
│ ├─ package.json
│ ├─ pnpm-lock.yaml
│ └─ next.config.ts
└─ sanity/
├─ package.json
├─ pnpm-lock.yaml
├─ sanity.blueprint.ts
├─ studio/
│ └─ sanity.config.ts
└─ functions/
└─ log-event/
└─ index.ts
```
Deploys run from inside `sanity/`. The manifest and lockfile are co-located there, so the CLI detects your package manager correctly with no extra flags. The frontend installs and builds on its own track, untouched by Function deploys.
This setup is fully supported.
### Multi-application project (recommended for monorepos)
This is the layout Turborepo and pnpm workspaces are built for, and it's where Blueprints belong once they manage more than just Functions.
**Example structure**
```text
my-project/
├─ apps/
│ ├─ functions/
│ │ ├─ package.json
│ │ └─ screen-cfp/
│ │ └─ index.ts
│ ├─ studio/
│ └─ web/
├─ packages/
│ └─ shared-utilities/
├─ package.json
├─ pnpm-lock.yaml
├─ pnpm-workspace.yaml
└─ sanity.blueprint.ts
```
The manifest sits at the root next to the lockfile. Each application, including the Functions workspace, owns its own `package.json`. The manifest references each Function via their definers `src: './apps/functions/'`. For example:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources:[
defineDocumentFunction({
name: 'screen-cfp',
event: {
on: ['create']
},
src: './apps/functions/screen-cfp'
})
]
})
```
With this layout you can use pnpm's `catalog:` and `workspace:` protocols freely:
**pnpm-workspace.yaml**
```yaml
packages:
- 'apps/*'
- 'packages/*'
catalog:
'@sanity/client': '^7.22.0'
'@sanity/functions': '^1.2.1'
```
Then in any workspace:
**apps/functions/package.json**
```json
{
"dependencies": {
"@sanity/client": "catalog:",
"@sanity/functions": "catalog:"
}
}
```
This setup is fully supported.
## Where dependencies live
The CLI looks for dependencies in two places, depending on what it finds.
**Function-level.** If a Function's directory contains a `package.json`, the CLI uses only those dependencies. Nothing else.
**Project-level.** Otherwise, the CLI uses the `package.json` next to `sanity.blueprint.ts`. In a pnpm workspace, that root `package.json` typically declares devDependencies for tooling, and each workspace member, such as `apps/functions/package.json`, owns the runtime dependencies its code imports.
Functions cannot mix both sources. If a Function has its own `package.json`, project-level dependencies are invisible to it. To use a project-level package at the function level, declare it in both places.
### pnpm strictness changes where deps must live
By default, pnpm enforces strict resolution: a workspace can only resolve dependencies declared in its own `package.json`, even if those dependencies exist in the root `node_modules`. Even though the Sanity CLI might be able to find the dependencies up to the root `package.json`, it’s better to follow the default practice and declare them in the workspace member that owns the Function code, typically `apps/functions/package.json`.
## How the CLI bundles your function
For TypeScript Functions in a pnpm workspace, the CLI bundles inline using Vite. Rollup, which Vite uses for production builds, tree-shakes unused exports. Each Function's bundle contains only the parts of its dependencies its source actually imports.
> [!WARNING]
> Non-TypeScript projects bundle full dependencies
> For npm or yarn projects that doesn’t use TypeScript, the CLI externalizes dependencies and ships them as a `node_modules` folder alongside the source. Per-file bundles are smaller, but the asset includes the full installed packages.
You can override the defaults per resource in the manifest:
**sanity.blueprint.ts**
```typescript
defineDocumentFunction({
name: 'log-event',
src: './apps/functions/log-event',
transpile: false,
autoResolveDeps: false,
event: {
on: ['create'],
filter: '_type == "event"',
projection: '{_id}',
resource: {type: 'dataset', id: 'production'},
},
})
```
- `transpile: false` is useful when a Function already emits its own build, for example `src: './apps/functions/log-event/dist'`.
- `autoResolveDeps: false` skips dependency hydration entirely.
## Asset size and native modules
Function assets are capped at 200 MB. The CLI checks this before upload.
Native Node modules, anything that includes a `.node` binary such as `sharp` or `better-sqlite3`, are rejected at build time. The Functions runtime is Node.js v24.x in a sandboxed environment that doesn't support them. If your Function needs image processing or other native work, use a JS-only alternative, or do the work outside the Function and pass the result(s) in.
## Anti-pattern: Manifest nested inside Studio
Don't put `sanity.blueprint.ts` inside the Studio directory. It breaks the lockfile rule today, and it gets in the way as your Blueprint grows to manage more resources over time.
**Avoid this layout**
```text
my-project/
├─ studio/
│ ├─ functions/
│ │ └─ log-event/
│ │ └─ index.ts
│ └─ sanity.blueprint.ts
├─ package.json
└─ pnpm-lock.yaml
```
Today, this breaks the lockfile rule. Editors typically run `pnpm dlx sanity@latest blueprints deploy` from `my-project/studio` because that's where the manifest sits. The lockfile is one level up, so the CLI can't detect it and falls back to npm. If any dependency uses `catalog:` or `workspace:`, the build fails with `EUNSUPPORTEDPROTOCOL`.
All three supported patterns above keep the manifest above the Studio. As your Blueprint accumulates more resources (more Functions, CORS origins, robot tokens, roles, datasets), it's easier to extend a manifest that already sits in the right place. Move `sanity.blueprint.ts` above the Studio directory now to avoid a forced migration later. If you can't restructure right now, pass `--fn-installer pnpm` on every deploy as a stopgap. The migration steps below cover the move.
## Migrate an existing project to root
If your manifest currently lives under `apps/studio/` or `apps/functions/`, here's how to move to the recommended layout without disturbing the deployed stack:
1. Move `sanity.blueprint.ts` to the repository root.
2. Update each `src:` path in the manifest from `'./'` to `'./apps/functions/'`, or wherever the Function code lives.
3. Declare runtime dependencies in the workspace that owns the Function code, not in the root `package.json`.
4. Rebind your local Blueprint config to the existing remote stack:
**npm**
```shell
npx sanity@latest blueprints init \
--project-id YOUR_PROJECT_ID \
--stack-id \
--blueprint-type ts
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init \
--project-id YOUR_PROJECT_ID \
--stack-id \
--blueprint-type ts
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init \
--project-id YOUR_PROJECT_ID \
--stack-id \
--blueprint-type ts
```
**bun**
```shell
bunx sanity@latest blueprints init \
--project-id YOUR_PROJECT_ID \
--stack-id \
--blueprint-type ts
```
1. Run `pnpm dlx sanity@latest blueprints plan`. The output should show only `~ update` lines, no creates or destroys. Bundles are re-hashed when the manifest moves, but no resources are added or removed.
2. Deploy: `pnpm dlx sanity@latest blueprints deploy`.
If `blueprints plan` shows resource creates or destroys, stop and check that the stack ID and project ID match what was previously deployed.
# Promote a stack
Every blueprint stack has a scope that determines which resource types it can manage. By default, stacks are scoped to a project. To deploy organization-level resources like scheduled functions, you need to promote the stack to organization scope.
## When you need organization scope
[Scheduled functions](https://www.sanity.io/docs/functions/scheduled-function-quickstart) (`sanity.function.cron`) run on a timer rather than responding to document changes in a specific project. Because they operate independently of any single project, they require organization scope.
If you add a scheduled function to a project-scoped stack and run `sanity blueprints deploy`, the deployment will fail with an error indicating that the resource requires organization scope. Promoting your stack resolves this.
## Prerequisites
- An existing project-scoped blueprint stack. If you have not initialized a blueprint yet, see the [Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction) or one of the Blueprint or Function guides.
- A role (such as Administrator) with the `sanity.organization.update` permission on the organization that owns the project. Project-level permissions alone are not sufficient.
- The project must belong to an organization. Standalone projects cannot be promoted.
- No active deployments or operations running on the stack.
- Deploying an organization-scoped blueprint requires an organization admin role, or a robot token with the `sanity.blueprints.deploy` permission.
## Check your current scope
Before promoting, confirm that your stack is currently project-scoped by running the `config` command:
**npm**
```shell
npx sanity@latest blueprints config
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints config
```
**yarn**
```shell
yarn dlx sanity@latest blueprints config
```
**bun**
```shell
bunx sanity@latest blueprints config
```
If the output shows `Scoped to: Project `, the stack is project-scoped and eligible for promotion.
## Promote the stack
Run the promote command from a directory containing your configured blueprint:
**npm**
```shell
npx sanity@latest blueprints promote
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints promote
```
**yarn**
```shell
yarn dlx sanity@latest blueprints promote
```
**bun**
```shell
bunx sanity@latest blueprints promote
```
The CLI will ask you to confirm the promotion. After confirming, the command performs a single atomic operation that:
- Changes the stack's scope from project to organization.
- Sets a value on the stack to preserve the original project ID so your existing project-scoped resources continue to work. You can also explicitly set the project for each resource, but this keeps your existing resources working as expected.
- Updates your local `.sanity/blueprint.config.json` by removing `projectId` and adding `organizationId`.
> [!TIP]
> No redeploy needed
> Promotion does not affect the state of already-deployed resources. Your existing document functions, webhooks, CORS origins, and other project-scoped resources continue working without any changes.
You can optionally pass the `--force` flag to skip the confirmation prompt, or `--stack ` to target a specific stack if you have more than one.
## Verify the promotion
After promotion, confirm the scope change by running the `config` command again:
**npm**
```shell
npx sanity@latest blueprints config
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints config
```
**yarn**
```shell
yarn dlx sanity@latest blueprints config
```
**bun**
```shell
bunx sanity@latest blueprints config
```
The output should now show `Scoped to: Organization `. You can also check `sanity blueprints logs` to see the promotion operation recorded in the stack's history.
## Deploy with scheduled functions
With the stack promoted, you can now define both project-scoped and organization-scoped resources in the same blueprint:
**sanity.blueprint.ts**
```typescript
import {
defineBlueprint,
defineDocumentFunction,
defineScheduledFunction,
} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
// Existing project-scoped resource, still works via defaultProjectId
defineDocumentFunction({
name: 'on-publish',
event: {on: ['create', 'update']},
// Or, explicitly set the project resource:
project: `YOUR_PROJECT_ID`
}),
// New org-scoped resource, enabled by promotion
defineScheduledFunction({
name: 'daily-digest',
event: {expression: '0 9 * * *'}, // you can also use the day, minute, hour, year syntax
}),
],
})
```
When you run `sanity blueprints deploy`, the scope resolver handles each resource appropriately. Project-scoped resources like document functions resolve through `project`, while organization-scoped resources like scheduled functions use the organization scope directly. See each definer’s [reference documentation](https://reference.sanity.io/_sanity/blueprints/) for further configuration details.
## Things to keep in mind
### Promotion is one-way
There is no command to demote a stack back to project scope. Organization scope is strictly broader than project scope, so an org-scoped stack can do everything a project-scoped stack can. If you promote by mistake, your existing resources continue working exactly as before.
### Configuration changes
The promote command automatically updates your `.sanity/blueprint.config.json` file. If your CI/CD pipeline reads from this file, no pipeline changes are needed. However, if your pipeline sets `SANITY_PROJECT_ID` as an environment variable, switch to `SANITY_ORGANIZATION_ID` after promotion.
### Multiple projects
After promotion, the stack is updated with details from the original project. To target resources in a different project, add an explicit `project` attribute to individual resource definitions. This allows a single org-scoped stack to manage resources across multiple projects.
### Stack limits
Stacks are limited to 3 per scope. After promotion, the stack belongs to the organization and is no longer counted against the project's stack limit. Stack names must be unique within a scope. If the organization already has a stack with the same name, the promotion will fail.
## Troubleshooting
### Permission denied (403)
Promotion requires the `sanity.organization.update` permission. If you receive a 403 error, ask an organization administrator to grant you the required permission.
### Operation in progress (409)
You cannot promote a stack while a deployment or other operation is active. Wait for the current operation to complete, then retry the promote command.
### Duplicate stack name
Stack names must be unique within a scope. If the organization already has a stack with the same name, promotion fails with a `DuplicateStackNameError`. To resolve this, use `--new-stack-name ` to rename while promoting.
### Stack already promoted
The promote command is idempotent. Running it on an already-promoted stack returns success without making any changes. You can safely retry the command if you are unsure whether a previous promotion completed.
# Deploy from CI
There may be instances where you want to deploy your Blueprint automatically from CI, without using our [official GitHub Action](https://www.sanity.io/docs/blueprints/blueprint-action). This page explains the flow step by step so you can run it on any CI system.
In CI, the deploy process involves four steps:
1. Install the Sanity runtime CLI.
2. Authenticate with a deploy token.
3. Set the project (or organization) and Stack to target.
4. Run blueprints deploy.
The sections below walk through each prerequisites and steps. Read on to understand the flow or to run your own deploy in another CI system.
## How CI differs from local development
On your own machine, two things work automatically that aren't available in CI:
- **Authentication.** You've run sanity login, so the CLI reads your credentials from disk. CI has no logged-in user.
- **Scope and Stack.** When you run sanity blueprints init, the CLI saves your project (or organization) and Stack IDs to .sanity/blueprint.config.json. That file is gitignored by default, so it isn't in a fresh CI checkout.
In CI you supply both explicitly: a token for authentication, and a few environment variables for your scope and Stack.
## Before you get started
This section assumes you have a Sanity project with a Blueprint initialized locally.
The Blueprints CLI commands require an authenticated token to run in CI. Create a deploy token with sanity blueprints mint-deploy-token, described below. It's the only credential your CI pipeline needs.
The deploy token can deploy your Stack, but it can't create a Stack or mint further tokens. Keep `init` and `mint-deploy-token` as local admin steps.
## Create a deploy token
Mint a deploy token with the CLI:
```sh
sanity blueprints mint-deploy-token --print
```
This prints the token to your terminal. Add it to your CI system as a secret, and don't commit it to your repository. Your CI job exposes it to the CLI as the SANITY_AUTH_TOKEN environment variable, which the CLI reads before any credentials on disk.
Minting a token requires admin access to the Stack's scope: project admin for a project-scoped Stack, or organization admin for an organization-scoped Stack. The minted token automatically carries the permissions needed to plan, deploy, and destroy Blueprints in that scope.
The minted token carries the Blueprints deploy role for the stack's scope: `blueprints-deployer` for a project-scoped Stack, or `blueprints-deployer-robot` for an organization-scoped Stack. The token also appears under Robots in Manage, where it can be revoked.
Useful flags: `--label ` sets a readable label, `--json` outputs the full result as JSON, and `--print` prints only the raw token for shell capture.
## Set your scope and Stack
Because .sanity/blueprint.config.json isn't in your CI, provide its values as environment variables. The CLI reads the following:
#### Properties
**SANITY_AUTH_TOKEN** (required)
The deploy token you created above.
**SANITY_PROJECT_ID** (string)
Required for project-scoped Stacks. Set this when your config has a projectId.
**SANITY_ORGANIZATION_ID** (string)
Required for org-scoped Stacks. Set this when your config has an organizationId.
**SANITY_BLUEPRINT_STACK_ID** (required)
The Stack to deploy (your ST-… ID). Note the singular BLUEPRINT in the variable name.
A Stack has a single scope, recorded in .sanity/blueprint.config.json. Open that file (or run sanity blueprints info) and set the matching variable in your CI settings: if it contains a projectId, set SANITY_PROJECT_ID; if it contains an organizationId, set SANITY_ORGANIZATION_ID. Set one, never both.
## Run the deploy
With the token and scope variables in your environment, the deploy is a single command. Substitute your package manager commands as needed.
**npm**
```shell
npm ci
npx -y sanity blueprints deploy
```
**pnpm**
```shell
npm ci
pnpm dlx -y sanity blueprints deploy
```
**yarn**
```shell
npm ci
yarn dlx -y sanity blueprints deploy
```
**bun**
```shell
npm ci
bunx -y sanity blueprints deploy
```
`deploy` waits for the deployment to finish and exits with a non-zero status if it fails, so your CI job fails when the deployment fails.
This is everything the GitHub Action does, run by hand.
## Plan on pull requests
`sanity blueprints plan` is read-only. It previews the changes a deploy would make without applying them. A common pattern is to run blueprints plan on pull requests so reviewers can see the intended change, and blueprints deploy when changes merge to your main branch. The plan command uses the same scope and Stack variables as deploy.
## Example: CircleCI
Because the steps are a combination of environment variables and a CLI command, the same flow works on any platform. Here it is end to end in CircleCI (.circleci/config.yml):
```yaml
version: 2.1
jobs:
deploy-blueprints:
docker:
- image: cimg/node:lts
environment:
# Non-secret values, safe to commit:
SANITY_PROJECT_ID: "1234xyz"
SANITY_BLUEPRINT_STACK_ID: "ST-1234xyz"
# SANITY_AUTH_TOKEN is set as a project environment variable in
# CircleCI (Project Settings > Environment Variables), not committed here.
steps:
- checkout
- run: npm ci
- run: npx -y sanity blueprints deploy
workflows:
deploy:
jobs:
- deploy-blueprints:
filters:
branches:
only: main
```
Set `SANITY_AUTH_TOKEN` as a project environment variable in CircleCI (Project Settings > Environment Variables). CircleCI injects it into the job automatically and the CLI reads it, so the token is never committed to your config file. Unlike GitHub Actions, there's no secret to reference in the config: the variable is simply present in the job's environment.
The pattern is the same everywhere: store the token as a secret, set your scope and Stack variables, and run deploy.
## Troubleshooting
### Start with diagnostics
`sanity blueprints doctor` reports what the CLI resolved in your CI environment: whether it found a valid token, which scope and Stack it resolved, and where each value came from (environment variable or config file). Run it as a step in your pipeline, or after a failed deploy, to see why a deploy failed.
### Deploys failing with a permissions error after promoting a Stack
A deploy token is scoped to a single project or organization. Promoting a Stack from project to organization scope does not re-scope the token. Your existing project-scoped token can no longer deploy the now organization-scoped Stack. To fix it:
1. Mint a new organization-scoped token: `sanity blueprints mint-deploy-token --organization-id your-org-id` (requires organization admin access).
2. Update your CI secret with the new token.
3. Replace `SANITY_PROJECT_ID` with `SANITY_ORGANIZATION_ID`.
The Stack ID doesn't change when you promote, so `SANITY_BLUEPRINT_STACK_ID` stays the same.
### Missing scope: provide --project-id or --organization-id
The CLI couldn't determine your target project or organization. In CI this is expected: .sanity/blueprint.config.json is gitignored and isn't in your checkout. Set SANITY_PROJECT_ID or SANITY_ORGANIZATION_ID (or pass the matching flag), as described in the Set your scope and Stack section above.
### Missing stack: provide --stack…
With no .sanity/ config in the checkout, the CLI doesn't know which Stack to deploy. Set SANITY_BLUEPRINT_STACK_ID (or pass `--stack`).
### Authentication failures
Check that SANITY_AUTH_TOKEN is set in your job environment, and that the token has the right deploy permission for your scope.
# Deploy with GitHub Actions
The official [Blueprints GitHub Actions](https://github.com/sanity-io/blueprints-actions) lets you add Blueprint planning and deployment to your existing GitHub workflows.
## Prerequisites
### Create a Blueprint
Before you get started, you should have a local blueprint configured and committed to the git repository you want to use. If you’re new to blueprints, you can [get started by creating a function](https://www.sanity.io/docs/functions/function-quickstart).
Before using these actions, you need **configuration values** from your project. Run the following command to retrieve your project and stack IDs.
**CLI input**
```sh
npx sanity blueprints config
```
**CLI output**
```sh
Current configuration:
Sanity Project:
Deployment ID:
```
### Create a Sanity API token
Next you’ll need a Sanity API token with permission to deploy the blueprint.
1. Go to [sanity.io/manage](https://www.sanity.io/manage).
2. Select your project or organization. Organization-scoped blueprints will require an organization-level token.
3. Go to **API** → **Tokens**.
4. Select **Add API token**.** **
5. Create a token with blueprint deploy permissions.
6. Copy the token (you won't be able to see it again).
If you’re creating tokens programatically, you’ll need the following permissions:
- Project-scoped: `sanity.project.blueprints.deploy`
- Organization-scoped: `sanity.blueprints.deploy`
### Add token to GitHub secrets
Next, add the API token to your GitHub secrets.
1. Go to your GitHub repository.
2. Navigate to **Settings **→ **Secrets and variables** → **Actions**.
3. Select **New repository secret**.
4. Name: `SANITY_TOKEN`.
5. Value: Paste your Sanity API token.
6. Select **Add secret**.
## Create your workflows
There are two actions available: deploy and plan.
The **Deploy action** executes `sanity blueprints deploy` in your GitHub workflow, automatically applying your Blueprint configuration to your Sanity project. It deploys your resources, like functions, and provides a deployment status output for use in your workflow.
Some ways you can use it are:
- On pushes to your main/production branch for continuous deployment.
- As part of a release workflow.
- For scheduled deployments.
- After manual workflow dispatch.
The **Plan action** runs `sanity blueprints plan` and automatically posts the results as a PR comment, giving your team visibility into what changes will be applied. It shows specific changes in the resources, as well as a summary of all changes.
Some ways you can use it are:
- Confirm what a blueprint will do before deploying.
- Automatically post results as a collapsible PR comment.
- Keep your PR discussions clean and organized.
### Create a Deploy workflow
Create `.github/workflows/deploy-blueprints.yml`. Replace the stack and project ID placeholders with your values.
**.github/workflows/deploy-blueprints.yml**
```yaml
name: Deploy Sanity Blueprints
on:
push:
branches:
- main
jobs:
deploy:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Install dependencies
run: npm ci # or pnpm/yarn
- name: Deploy blueprints
uses: sanity-io/blueprints-actions/deploy@deploy-v3
with:
sanity-token: ${{ secrets.SANITY_TOKEN }}
stack-id: 'ST_1234xyz'
project-id: '1234xyz'
# organization-id: '1234xyz' # if you're deploying an org-scoped blueprint
```
### Create a Plan workflow
Create `.github/workflows/plan-blueprints.yml`. Replace the stack and project ID placeholders with your values.
**.github/workflows/plan-blueprints.yml**
```yaml
name: Sanity Blueprints Plan
on:
pull_request:
permissions:
contents: read
pull-requests: write # Required for posting comments
jobs:
plan:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Install dependencies
run: npm ci # or pnpm/yarn
- name: Plan blueprints changes
uses: sanity-io/blueprints-actions/plan@plan-v2
with:
sanity-token: ${{ secrets.SANITY_TOKEN }}
stack-id: 'ST_1234xyz'
project-id: '1234xyz'
# organization-id: '1234xyz' # if you're planning an org-scoped blueprint
```
### Custom working directory
If your blueprint isn’t at the root of your repository, add `working-directory`.
**deploy-blueprint.yml**
```yaml
name: Sanity Blueprints Plan
on:
pull_request:
permissions:
contents: read
pull-requests: write # Required for posting comments
jobs:
plan:
runs-on: ubuntu-latest
steps:
- name: Checkout repository
uses: actions/checkout@v5
- name: Install dependencies
run: npm ci # or pnpm/yarn
- name: Plan blueprints changes
uses: sanity-io/blueprints-actions/plan@plan-v2
with:
sanity-token: ${{ secrets.SANITY_TOKEN }}
stack-id: 'ST_1234xyz'
project-id: '1234xyz'
working-directory: 'path/to/blueprints'
```
### Use deployment status in workflow
The deploy action logs the deployment progress and provides a `deployment-status` output you can use in subsequent workflow steps. For example:
**action output**
```yaml
- name: Deploy blueprints
id: deploy
uses: sanity-io/blueprints-actions/deploy@deploy-v3
with:
sanity-token: ${{ secrets.SANITY_TOKEN }}
stack-id: 'ST_1234xyz'
project-id: '1234xyz'
- name: Notify on success
if: steps.deploy.outputs.deployment-status == 'success'
run: echo "Deployment successful!"
```
## Configuration Reference
#### Properties
**sanity-token** (string, required)
A Sanity API token with deploy permissions.
**stack-id** (string, required)
The blueprint stack ID. Find this by running sanity blueprints config to view the active stack, or sanity blueprints stacks view all current stacks.
**project-id** (string, required)
Sanity project ID. Find this by running sanity blueprints config or in your project settings at sanity.io/manage. Only use when not using an organization-id.
**organization-id** (string, required)
Set the Sanity organization ID for organization-scoped stacks. Only use when not using a project-id.
**working-directory** (string)
Path to the directory containing your blueprint config (sanity.blueprint.ts). Defaults to the repository root.
Visit the [GitHub Actions Repository](https://github.com/sanity-io/blueprints-actions) for additional details.
# Define a webhook
With [webhooks](https://www.sanity.io/docs/content-lake/webhooks) you can send customized HTTP requests when documents in your Content Lake change. If you also need code to run when documents change, [you should try Functions](https://www.sanity.io/docs/functions/functions-introduction).
In this guide, you’ll define a webhook resource with Blueprints and deploy the blueprint to Sanity.
Prerequisites:
- The latest version of `sanity` CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with `npx sanity@latest`.
- An existing project and [a role with permission](https://www.sanity.io/docs/content-lake/roles-concepts) to edit webhooks (requires the `sanity-project-webhooks` permission).
- Webhook support was first introduced in `@sanity/blueprints` v0.11.0. We recommend using the latest version of the library.
## Initialize a new blueprint
To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
## Configure the document webhook
Add the `defineDocumentWebhook` helper to your `sanity.blueprint.ts` configuration to define a webhook.
**sanity.blueprint.ts**
```
import { defineBlueprint, defineDocumentWebhook } from "@sanity/blueprints"
export default defineBlueprint({
resources: [
defineDocumentWebhook({
name: 'my-webhook',
on: ['create'],
url: 'https://example.com/webhook',
filter: '_type == "post"',
projection: '{_id}',
dataset: 'production',
apiVersion: 'v2026-01-01',
})
],
})
```
A full list of available configuration options is available in the [reference documentation](https://reference.sanity.io/_sanity/blueprints/defineDocumentWebhook/).
## Deploy the blueprint
Once you’ve configured your webhook, deploy the blueprint.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
Once the deployment finishes, your webhook will begin sending updates whenever a document changes that matches the configuration.
If you need to make changes, update the blueprint file (`sanity.blueprint.ts`) and run the deploy command again.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
## Learn more about webhooks
#### Explore webhooks
[GROQ-powered webhooks](https://www.sanity.io/docs/content-lake/webhooks)
Send customized HTTP requests when something in your Content Lake has changed.
[GROQ-Powered Webhooks – Intro to Filters](https://www.sanity.io/docs/developer-guides/filters-in-groq-powered-webhooks)
A thorough intro to using GROQ-filters in a webhook-context
[GROQ-Powered Webhooks – Intro to Projections](https://www.sanity.io/docs/developer-guides/projections-in-groq-powered-webhooks)
A thorough intro to using GROQ-projections in a webhook contest
# Define a CORS origin
CORS is a security mechanism that allows browsers to safely make requests across different origins. Without it, the browser's Same-Origin Policy would block your Sanity Studio from communicating with the Sanity API, since they run on different domains.
In this guide, you’ll define a CORS origin resource with Blueprints and deploy the blueprint to Sanity.
Prerequisites:
- The latest version of `sanity` CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with `npx sanity@latest`.
- An existing project and [a role with permission](https://www.sanity.io/docs/content-lake/roles-concepts) to edit a project’s CORS origins (requires the `sanity-project-cors` permission).
- CORS support was first introduced in `@sanity/blueprints` v0.11.0. We recommend using the latest version of the library.
## Initialize a new blueprint
To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
## Configure the CORS origin
Use the `defineCorsOrigin` helper to define an origin.
**sanity.blueprint.ts**
```
import { defineBlueprint, defineCorsOrigin } from "@sanity/blueprints"
export default defineBlueprint({
resources: [
defineCorsOrigin({
name: 'studio-origin',
origin: 'https://your-studio.your-domain.com',
// allowCredentials: true, // optional, only set if needed
})
],
})
```
A full list of available configuration options is available in the [reference documentation](https://reference.sanity.io/_sanity/blueprints/defineCorsOrigin/).
## Deploy the blueprint
Next, deploy the blueprint.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
Once the deployment finishes, your CORs origin resource is active.
If you need to make changes, update the blueprint file (`sanity.blueprint.ts`) and run the deploy command again.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
## Learn more about CORS
#### Explore CORS
[Access your data (CORS)](https://www.sanity.io/docs/content-lake/cors)
Decide which websites can access your project data.
[CORS and browser security](https://www.sanity.io/docs/content-lake/browser-security-and-cors)
Best practices for configuring CORS origins securely while letting trusted websites interact with your Sanity Dataset.
[CORS CLI command reference](https://www.sanity.io/docs/cli-reference/cors-in-cli)
Interact with CORS-entries for your project
# Define a robot token
[Robot tokens](https://www.sanity.io/docs/content-lake/http-auth) let your code make authenticated requests to Sanity. When created with Blueprints, they’re often used to provide explicit access in [Functions](https://www.sanity.io/docs/functions/robot-tokens-with-functions).
In this guide, you’ll define a robot token resource with Blueprints and deploy the blueprint to Sanity.
Prerequisites:
- The latest version of `sanity` CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with `npx sanity@latest`.
- An existing project and [a role with permission](https://www.sanity.io/docs/content-lake/roles-concepts) to edit robot tokens (requires the `sanity-project-tokens` permission).
- Robot token support was first introduced in `@sanity/blueprints` v0.11.0. We recommend using the latest version of the library.
## Initialize a new blueprint
To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
## Configure the robot token
Use the `defineRobotToken` helper to define a robot token resource.
**sanity.blueprint.ts**
```
import { defineBlueprint, defineRobotToken } from "@sanity/blueprints"
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'editor-robot',
memberships: [
{
resourceType: 'project',
resourceId: 'YOUR_PROJECT_ID',
roleNames: ['editor']
}
]
})
],
})
```
A full list of available configuration options is available in the [reference documentation](https://reference.sanity.io/_sanity/blueprints/defineRobotToken/).
## Use the token in a function
Reference the token in your function definition to make it available to your custom functions. This makes the function use the custom-scoped robot token instead of the default token with broad read/write permissions.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineRobotToken, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'editor-robot',
memberships: [
{
resourceType: 'project',
resourceId: 'YOUR_PROJECT_ID',
roleNames: ['editor']
}
]
}),
defineDocumentFunction({
name: 'my-function',
// Replace `editor-robot` with your token name
robotToken: '$.resources.editor-robot.token',
// ... rest of config
}),
]
})
```
## Deploy the blueprint
Next, deploy the blueprint.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
Once the deployment finishes, the robot token is active.
If you need to make changes, update the blueprint file (`sanity.blueprint.ts`) and run the deploy command again.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
## Learn more about robot tokens
#### Explore robot tokens
[Using robot tokens with Functions](https://www.sanity.io/docs/functions/robot-tokens-with-functions)
Learn how to authenticate Sanity Functions using robot tokens defined with Blueprints.
[Authentication and tokens](https://www.sanity.io/docs/content-lake/http-auth)
How to create tokens and make authenticated requests.
[Roles](https://www.sanity.io/docs/user-guides/roles)
Sanity enforces user access control with roles. Roles help control resource access to datasets and documents.
# Define a custom role
Blueprints allow you to define [custom roles](https://www.sanity.io/docs/user-guides/roles) alongside other resources. Roles are sets of permissions that can be assigned to users and robot tokens. You can even combine roles and robot tokens with Blueprints to provide explicit access in [Functions](https://www.sanity.io/docs/functions/robot-tokens-with-functions).
**This is a paid feature**
This feature is available on certain Enterprise plans. [Talk to sales](https://www.sanity.io/contact/sales?ref=docs) to learn more.
In this guide, you’ll define a custom role resource with Blueprints and deploy the blueprint to Sanity.
Prerequisites:
- The latest version of `sanity` CLI is recommended to interact with Blueprints. You can always run the latest CLI commands with `npx sanity@latest`.
- An existing project and [a role with permission](https://www.sanity.io/docs/content-lake/roles-concepts) to edit roles (requires the `sanity-project-roles` permission).
- Custom role support was first introduced in `@sanity/blueprints` v0.11.0. We recommend using the latest version of the library.
## Initialize a new blueprint
To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --project-id --stack-name production
```
To initialize a blueprint in the current directory, run the command below. Replace the project ID with your own. Skip to the next section if you already have a blueprint set up.
## Configure the custom resource
Use the `defineRole` helper to define a custom role resource.
**sanity.blueprint.ts**
```
import { defineBlueprint, defineRole } from "@sanity/blueprints"
export default defineBlueprint({
resources: [
defineRole({
name: 'custom-robot-role',
title: 'Custom Robot Role',
appliesToRobots: true,
permissions: [{
name: 'sanity-project-cors',
action: 'create',
}],
})
],
})
```
A full list of available configuration options is available in the [reference documentation](https://reference.sanity.io/_sanity/blueprints/defineRole/). You can learn more about the parts that make up a role in the [roles and permissions documentation](https://www.sanity.io/docs/content-lake/roles-concepts).
## Deploy the blueprint
N, deploy the blueprint.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
Once the deployment finishes, the custom role is active.
If you need to make changes, update the blueprint file (`sanity.blueprint.ts`) and run the deploy command again.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
## Learn more about roles
#### Explore roles
[Roles and permissions](https://www.sanity.io/docs/content-lake/roles-concepts)
Concepts behind Sanity's roles and permissions system: resources, permissions, roles, and users, plus when to reach for custom roles.
[Roles user guide](https://www.sanity.io/docs/user-guides/roles)
Configure and assign roles in your project or organization settings
# Configuration file
[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. Right now this is limited to Function resources, but will expand in the future.
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 | Reusable constants, referenced with $.values.. Values are always strings. |
> [!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 function 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 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](https://reference.sanity.io/_sanity/blueprints/defineDocumentFunction/).
#### `event` properties
#### 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 ..
You can set to * to signify "all datasets in the project with ID ."
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)**
```
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
{
"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.
- [CORS reference](https://reference.sanity.io/_sanity/blueprints/defineCorsOrigin/)
- [Webhooks reference](https://reference.sanity.io/_sanity/blueprints/defineDocumentWebhook/)
- [Media Library Asset Function reference](https://reference.sanity.io/_sanity/blueprints/defineMediaLibraryAssetFunction/)
- [Robot token reference](https://reference.sanity.io/_sanity/blueprints/defineRobotToken/)
- [Role reference](https://reference.sanity.io/_sanity/blueprints/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. | A value from the values block, resolved when the file runs. |
| $.resources. | Another resource in the file. Creates a dependency edge. |
| $.resources..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.
# Blueprints glossary
Definitions of the core Blueprints terms. For a narrative introduction, see the [Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction).
##### Blueprints glossary
| Term | Definition |
| --- | --- |
| Attach / detach | Bring an existing resource under Blueprints management (attach), or stop managing it without deleting it (detach). |
| Blueprint config file | .sanity/blueprint.config.json. Links a local blueprint file to a remote stack and records the scope. Gitignored by default; not secret. |
| Blueprint file | The file you edit, sanity.blueprint.ts, declaring your desired resources. Also called the manifest. See the Blueprint configuration reference. |
| Blueprints | Sanity's infrastructure-as-code system for managing resources from a file in your repo. |
| Definer | A typed function such as defineCorsOrigin or defineRole that declares a resource and checks your input as you write it. |
| Deletion policy | A per-resource setting (allow, retain, replace, protect) controlling what happens when a resource is removed or a stack is destroyed. |
| Deploy | Applying the blueprint file to a stack so resources match it. The command is blueprints deploy. |
| Destroy | Removing a stack's resources, subject to their deletion policies. The command is blueprints destroy. |
| Organization scope | A stack scoped to an organization. Unlocks org-scoped resource types and spans multiple projects. See the Blueprints scopes reference. |
| Plan | The read-only, deterministic diff between your blueprint file and a stack's current state. The command is blueprints plan. |
| Project scope | A stack scoped to a single project. |
| Promotion | Converting a project-scoped stack to organization scope. One-way and safe. See Promote a stack to organization scope. |
| Reference ($ syntax) | In-file pointers: $.values. for a constant, $.resources. for another resource (which creates a dependency edge). See The resource graph. |
| Resource | A single thing Blueprints manages: a dataset, CORS origin, webhook, role, robot token, or function. Has a unique name. |
| Rollback | Blueprints' best-effort attempt to undo completed changes, in reverse, when a deploy fails partway. See Errors and rollbacks. |
| Scope | The boundary a stack operates within: project or organization. |
| Stack | The deployed counterpart to a blueprint file: the live resources on Sanity's side. One file can deploy to many stacks. |
| Value | A reusable, file-level constant (always a string) defined in the values block and referenced with $.values.. |
#### Related
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.
[The resource graph](https://www.sanity.io/docs/blueprints/resource-graph)
How resources reference each other with the $ syntax, and why a blueprint file is a connected system.
[Errors and rollbacks](https://www.sanity.io/docs/blueprints/errors-and-rollbacks)
How Blueprints catches mistakes early and what happens when a deploy fails.
# Blueprints scopes reference
## The two scopes
##### The two scopes
| Scope | Boundary | Stored as |
| --- | --- | --- |
| Project | One Sanity project. Resources default to that project. | projectId in the config file |
| Organization | An organization. Project-scoped resources must name their project. Unlocks org-scoped resource types. | organizationId in the config file |
The blueprint file doesn't encode scope. Scope lives in `.sanity/blueprint.config.json` and is derived from which ID it holds.
## What needs which scope
Most resource types are project-scoped: they belong to a single project, and on an organization-scoped stack you give each one a `project`. A few require organization scope, such as scheduled (cron) functions. Roles are unscoped.
Deploying an organization-scoped type to a project-scoped stack fails; promote the stack first (see [Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)). For the current scope of each resource type, see the [typed API reference](https://reference.sanity.io/_sanity/blueprints/).
## How the CLI resolves scope
For each of `organizationId`, `projectId`, and `stackId`, the CLI takes the first source that resolves, in this order:
1. Command-line flags (`--organization-id`, `--project-id`, `--stack`)
2. Environment variables (`SANITY_ORGANIZATION_ID`, `SANITY_PROJECT_ID`, `SANITY_BLUEPRINT_STACK_ID`)
3. IDs exported from the blueprint file module
4. The local config file, `.sanity/blueprint.config.json`
Scope is derived as specifically as possible: if a project ID resolves, the scope is project; otherwise, if an organization ID resolves, the scope is organization.
## After promotion
When you [promote](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope) a stack to organization scope, it remembers its original project. Project-scoped resources that don't set a `project` fall back to that project automatically, so your existing resources keep working. Set an explicit `project` on a resource to target a different one.
#### Related
[Stacks and scope](https://www.sanity.io/docs/blueprints/stacks-and-scope)
How one blueprint file maps to many stacks, and what project versus organization scope means.
[Promote a stack to organization scope](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope)
Learn how to promote an existing project-scoped blueprint stack to organization scope to unlock scheduled functions.
[Blueprint configuration reference](https://www.sanity.io/docs/blueprints/blueprint-config)
Reference documentation for the Blueprint configuration files.
# Blueprints CLI commands
The `blueprints` CLI command enables initializing, managing, and deploying Blueprints and resources like Functions.
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
[Functions introduction](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.
**npm**
```shell
npx sanity blueprints --help
```
**pnpm**
```shell
pnpm dlx sanity blueprints --help
```
**yarn**
```shell
yarn dlx sanity blueprints --help
```
**bun**
```shell
bunx sanity blueprints --help
```
## Commands
### `add`
**CLI output**
```sh
USAGE
$ sanity blueprints add TYPE [--install] [-n ] [--example ] [--fn-helpers] [--fn-installer ] [--fn-type ] [--javascript] [--json] [--language ]
ARGUMENTS
TYPE Type of resource to add (only "function" is supported)
FLAGS
-i, --install Shortcut for --fn-installer npm
-n, --name= Name of the resource to add
--example= Example to use for the function resource. Discover examples at https://www.sanity.io/exchange/type=recipes/by=sanity
--fn-helpers Add helpers to the new function
--fn-installer= Which package manager to use when installing the @sanity/functions helpers
--fn-type= Document change event(s) that should trigger the function; you can specify multiple events by specifying this flag multiple times
--javascript Use JavaScript instead of TypeScript
--json Format output as json
--language= Language of the new function
DESCRIPTION
This command is deprecated. Use "functions add" instead.
Equivalent usage:
$ <%= config.bin %> functions add
$ <%= config.bin %> functions add --name my-function --type document-create
EXAMPLES
$ sanity blueprints add function
$ sanity blueprints add function --helpers
$ sanity blueprints add function --name my-function
$ sanity blueprints add function --name my-function --fn-type document-create
$ sanity blueprints add function --name my-function --fn-type document-create --fn-type document-update --lang js
```
### `config`
**CLI output**
```sh
USAGE
$ sanity blueprints config [--edit] [--json] [--organization-id ] [--project-id ] [--stack ]
FLAGS
-e, --edit Modify the configuration interactively, or directly when combined with ID flags.
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID to set in the configuration. Requires --edit flag
DESCRIPTION
Manages the local Blueprint configuration, which links your Blueprint to a Sanity project and Stack.
Without flags, displays the current configuration. Use --edit to interactively modify settings, or combine --edit with ID flags to update values directly (useful for scripting and automation).
If you need to switch your Blueprint to a different Stack, use --edit --stack.
EXAMPLES
$ sanity blueprints config
$ sanity blueprints config --edit
$ sanity blueprints config --edit --project-id
$ sanity blueprints config --edit --project-id --stack
```
### `deploy`
**CLI output**
```sh
USAGE
$ sanity blueprints deploy [-m ] [--json] [--new-stack-name ] [--no-wait] [--organization-id ] [--project-id ] [--stack ]
FLAGS
-m, --message= Message describing the deployment (e.g. reason for change)
--json Format output as json
--new-stack-name= Set a new name for the Stack
--no-wait Do not wait for Stack deployment to complete
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Applies your local Blueprint to the remote Stack, creating, updating, or removing resources as needed. This is the primary command for applying infrastructure changes.
Before deploying, run 'blueprints plan' to preview changes. After deployment, use 'blueprints info' to verify Stack status or 'blueprints logs' to monitor activity.
Use --no-wait to queue the deployment and return immediately without waiting for completion.
Use --fn-installer to force which package manager to use when deploying functions.
Set SANITY_ASSET_TIMEOUT (seconds) to override the 180-second timeout for processing resource assets.
Set SANITY_ASSET_CONCURRENCY to override how many resource assets are processed at once (default 4).
Exit codes: 0 deployed, 2 deployment failed, 75 deployment accepted but completion could not be confirmed (rerun 'blueprints info' to check).
EXAMPLES
$ sanity blueprints deploy
$ sanity blueprints deploy --message "Enable staging dataset"
$ sanity blueprints deploy --no-wait
$ sanity blueprints deploy --fn-installer npm
$ sanity blueprints deploy --stack
$ sanity blueprints deploy --organization-id --stack
$ sanity blueprints deploy --new-stack-name
```
### `destroy`
**CLI output**
```sh
USAGE
$ sanity blueprints destroy [--force] [--json] [--no-wait] [--organization-id ] [--project-id ] [--stack ]
FLAGS
-f, --force Force Stack destruction (skip confirmation)
--json Format output as json
--no-wait Do not wait for Stack destruction to complete
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID to destroy (defaults to the locally configured Stack)
DESCRIPTION
Permanently removes the remote Stack and all its provisioned resources. Your Blueprint manifest and resource files remain intact; "stackId" is unset in your local config.
This is a destructive operation. You will be prompted to confirm unless --force is specified.
Use this to clean up test environments or decommission a Stack you no longer need.
Exit codes: 0 destroyed, 2 destruction failed, 75 destruction accepted but completion could not be confirmed (rerun 'blueprints info' to check).
EXAMPLES
$ sanity blueprints destroy
$ sanity blueprints destroy --stack --project-id --force --no-wait
```
### `doctor`
**CLI output**
```sh
USAGE
$ sanity blueprints doctor [-p ] [--fix] [--json]
FLAGS
-p, --path= Path to a Blueprint file or directory containing one
--fix Interactively fix configuration issues
--json Format output as json
DESCRIPTION
Analyzes your local Blueprint and remote Stack configuration for common issues, such as missing authentication, invalid project references, or misconfigured resources.
Run this command when encountering errors with other Blueprint commands. Use --fix to interactively resolve detected issues.
Supports --json for programmatic consumption of diagnostic results.
EXAMPLES
$ sanity blueprints doctor
$ sanity blueprints doctor --fix
```
### `info`
**CLI output**
```sh
USAGE
$ sanity blueprints info [--verbose] [--json] [--organization-id ] [--project-id ] [--stack ]
FLAGS
-v, --verbose Show resource and external IDs
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID
DESCRIPTION
Displays the current state and metadata of your remote Stack deployment, including deployed resources, status, and configuration.
Use this command to verify a deployment succeeded, check what resources are live, or confirm which Stack your local Blueprint is connected to.
Run 'blueprints stacks' to see all available Stacks in your project or organization.
EXAMPLES
$ sanity blueprints info
$ sanity blueprints info --stack
$ sanity blueprints info --project-id --stack
$ sanity blueprints info --organization-id --stack
```
### `init`
**CLI output**
```sh
USAGE
$ sanity blueprints init [DIR] [--blueprint-type ] [--dir ] [--example ] [--json] [--organization-id ] [--project-id ] [--stack-id ] [--stack-name ]
ARGUMENTS
[DIR] Directory to create the local Blueprint in (defaults to the current directory)
FLAGS
--blueprint-type= Blueprint manifest type to use for the local Blueprint
--dir= Directory to create the local Blueprint in
--example= Example to use for the local Blueprint
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack-id= Existing Stack ID used to scope local Blueprint
--stack-name= Name to use for a new Stack provisioned during initialization
DESCRIPTION
A Blueprint is your local infrastructure-as-code configuration that defines Sanity resources (datasets, functions, etc.). A Stack is the remote deployment target where your Blueprint is applied.
This is typically the first command you run in a new project. It creates a local Blueprint manifest file (sanity.blueprint.ts, .js, or .json) and provisions a new remote Stack.
Additionally, a Blueprint configuration file is created in .sanity/ containing the scope and Stack IDs. A .gitignore covering node_modules, .env, and Function build output is created or updated; the .sanity/ config itself is not ignored.
After initialization, use 'blueprints plan' to preview changes, then 'blueprints deploy' to apply them.
Running without a directory prompts to confirm the current directory. Run 'blueprints init .' to initialize in the current directory without a prompt.
EXAMPLES
$ sanity blueprints init
$ sanity blueprints init .
$ sanity blueprints init [directory]
$ sanity blueprints init --blueprint-type
$ sanity blueprints init --organization-id
$ sanity blueprints init --project-id
$ sanity blueprints init --stack-name
$ sanity blueprints init --stack-id
$ sanity blueprints init new-stack --type --org --name
$ sanity blueprints init old-stack --type --project-id --stack-id
```
### `logs`
**CLI output**
```sh
USAGE
$ sanity blueprints logs [-l ] [--watch] [--before ] [--json] [--organization-id ] [--project-id ] [--since ] [--stack ]
FLAGS
-l, --limit= Maximum number of log entries to retrieve (1-500)
-w, --watch Watch for new Stack logs
--before= Only show logs before this ISO 8601 timestamp
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--since= Only show logs after this ISO 8601 timestamp
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Retrieves Stack deployment logs, useful for debugging and monitoring deployment activity.
Use --watch (-w) to tail logs in real-time.
Use --limit, --since, or --before to narrow the result set when not watching.
If you're not seeing expected logs, verify your Stack is deployed with 'blueprints info'.
EXAMPLES
$ sanity blueprints logs
$ sanity blueprints logs --watch
$ sanity blueprints logs --stack
$ sanity blueprints logs --limit 500
$ sanity blueprints logs --since 2026-05-01T00:00:00Z
$ sanity blueprints logs --before 2026-05-01T00:00:00Z
```
### `mint-deploy-token`
**CLI output**
```sh
USAGE
$ sanity blueprints mint-deploy-token [--print] [--json] [--label ] [--organization-id ] [--project-id ]
FLAGS
-P, --print Print only the raw token to stdout (suitable for shell substitution)
--json Format output as json
--label= Human-readable label for the robot. Defaults to a generated value.
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
DESCRIPTION
Mints a long-lived robot token with the role required to plan, deploy, and destroy Blueprints in this project or organization.
By default the command runs interactively and asks how you want to receive the token (clipboard, print, or exit). Use --print to emit only the raw token for shell pipelines, or --json for full API output.
The minted token is also visible in your Sanity Manage UI under Robots, where it can be revoked.
EXAMPLES
$ sanity blueprints mint-deploy-token
$ sanity blueprints mint-deploy-token --label "ci-deploy"
$ sanity blueprints mint-deploy-token --print
$ export SANITY_AUTH_TOKEN=$(sanity blueprints mint-deploy-token --print)
$ sanity blueprints mint-deploy-token --json
$ sanity blueprints mint-deploy-token --project-id
$ sanity blueprints mint-deploy-token --organization-id
```
### `plan`
**CLI output**
```sh
USAGE
$ sanity blueprints plan [--json] [--organization-id ] [--project-id ] [--stack ]
FLAGS
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Use this command to preview what changes will be applied to your remote Stack before deploying. This is a safe, read-only operation—no resources are created, modified, or deleted.
Run 'blueprints plan' after making local changes to your Blueprint manifest to verify the expected diff. When ready, run 'blueprints deploy' to apply changes.
EXAMPLES
$ sanity blueprints plan
$ sanity blueprints plan --stack
$ sanity blueprints plan --organization-id --stack
```
### `promote`
**CLI output**
```sh
USAGE
$ sanity blueprints promote [--force] [--json] [--new-stack-name ] [--project-id ] [--stack ]
FLAGS
--force Skip confirmation prompt
--json Format output as json
--new-stack-name= Set a new name for the Stack while promoting
--project-id= Sanity project ID used to scope Blueprint and Stack
--stack= Stack name or ID to promote
DESCRIPTION
Promotes a deployed Stack to organization scope, enabling management of org-level resources. Promotion cannot be reversed.
Your local Blueprint configuration will be updated to reflect the new scope.
EXAMPLES
$ sanity blueprints promote
$ sanity blueprints promote --stack
$ sanity blueprints promote --project-id --stack
$ sanity blueprints promote --new-stack-name
```
### `stacks`
**CLI output**
```sh
USAGE
$ sanity blueprints stacks [--all] [--include-projects] [--json] [--organization-id ] [--project-id ]
FLAGS
--all List Stacks from every organization and project you have access to
--include-projects Include Stacks from all projects within the organization. Requires --organization-id.
--json Format output as json
--organization-id= Sanity organization ID used to scope Blueprint and Stack
--project-id= Sanity project ID used to scope Blueprint and Stack
DESCRIPTION
Shows all Stacks associated with a project or organization. By default, lists Stacks scoped to the local Blueprint.
Use this to discover existing Stacks you can scope a local Blueprint to (using 'blueprints config --edit'), or to audit what's deployed across your project.
Without a scope, prompts for an organization or project. Use --all to list Stacks across every organization and project you can access, or --include-projects with --organization-id for one organization and its projects.
EXAMPLES
$ sanity blueprints stacks
$ sanity blueprints stacks --all
$ sanity blueprints stacks --project-id
$ sanity blueprints stacks --organization-id
$ sanity blueprints stacks --organization-id --include-projects
```
# Deploy custom functions to automate content operations
#### Create your first function
[Create a Document Function](https://www.sanity.io/docs/functions/function-quickstart)
Start building with Functions by deploying a new function to Sanity's infrastructure.
[Create a Media Library Asset Function](https://www.sanity.io/docs/functions/asset-function-quickstart)
Start building a function that reacts to changes to a Media Library asset.
[Official recipes](https://www.sanity.io/recipes)
Get started with pre-built functions for popular use cases
#### Core concepts and guides
[Introduction](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.
[Testing functions locally](https://www.sanity.io/docs/functions/functions-local-testing)
Simulate Functions locally with real data and an interactive playground.
[Configure @sanity/client in Functions](https://www.sanity.io/docs/functions/functions-js-client)
Learn to use the JavaScript client in a Sanity Function.
[Add environment variables to functions](https://www.sanity.io/docs/functions/function-env-vars)
Learn to add environment variables to your functions.
[Functions cheat sheet](https://www.sanity.io/docs/functions/functions-cheatsheet)
Common patterns and techniques for creating Functions.
# Introduction
Functions enable you to execute custom logic whenever changes occur in your content—all without requiring your own infrastructure.
With Functions, you can:
- Enrich, validate, and constrain your content in new ways.
- Create complex workflows.
- Connect changes in your content to external applications and services. Refresh a CDN cache, trigger social posts, update inventory, and more.
#### Get started
[Create a Document Function](https://www.sanity.io/docs/functions/function-quickstart)
Start building with Functions by deploying a new function to Sanity's infrastructure.
[Create a Scheduled Function](https://www.sanity.io/docs/functions/scheduled-function-quickstart)
Create your first scheduled function, a Sanity function that runs on a set schedule, with Blueprints.
[Create a Sync Tag Invalidate Function](https://www.sanity.io/docs/functions/sync-tag-function-quickstart)
Build and deploy a new Sync Tag Invalidate function to Sanity's infrastructure.
[Create a Media Library Asset Function](https://www.sanity.io/docs/functions/asset-function-quickstart)
Start building a function that reacts to changes to a Media Library asset.
[Official Function recipes](https://www.sanity.io/exchange/type=schemas/by=sanity)
Function recipes from the Sanity team
## Requirements
- Functions run on **Node.js v24.x**. We encourage you to use the same version in local testing to avoid unsupported features or syntax changes. You can adjust the runtime version with the `runtime` [configuration setting](https://reference.sanity.io/_sanity/blueprints/defineDocumentFunction/).
- The lastest version of the `sanity` CLI is recommended for interacting with Blueprints and Functions. You can always run the latest CLI commands with `npx sanity@latest`.
## Core concepts
### Functions
Functions are small, single-purpose pieces of code that run on Sanity's cloud infrastructure. They act on changes in your content and allow you to extend the capabilities of your existing content management workflows.
When changes in your content trigger a function, they pass along details about the document. [Using GROQ, you can further refine](https://www.sanity.io/docs/functions/function-quickstart):
- What *kinds* of content changes trigger a function using GROQ filters.
- What *sections* of content are passed to functions using GROQ projections.
Functions can access the full range of Sanity's APIs so you can interact with all of your content, not just the document that triggered the change.
#### Function types
There are different types of functions you can use for different parts of Sanity, and different invoking scenarios. The available function types are:
- [Document functions](https://www.sanity.io/docs/functions/function-quickstart) (`sanity.function.document`): React to any document changes in a project dataset.
- [Media Library Asset functions](https://www.sanity.io/docs/functions/asset-function-quickstart) (`sanity.function.media-library.asset`): React to asset changes in Media Library. This is limited to the `sanity.asset` document type.
- [Sync tag invalidate functions](https://www.sanity.io/docs/functions/sync-tag-function-quickstart) (`sanity.function.sync-tag-invalidate`): React to changes in your Live Content by way of sync tags.
- [Scheduled functions](https://www.sanity.io/docs/functions/scheduled-function-quickstart) (`sanity.function.cron`): Run your code on Sanity’s infrastructure at a set interval.
- [PubSub functions](https://www.sanity.io/docs/functions/pubsub-function-quickstart) (`sanity.function.pubsub`): A function you can invoke from other functions.
More function types will come in the future.
#### Organizing Functions
All function code resides in a dedicated directory for each individual function.
**Example directory structure**
```text
marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│ ├─ my-function/ <-- directory matches the function name
│ │ ├─ index.ts
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
```
You can treat functions as individual projects, with packages included in their individual `package.json` files, or as part of a larger system with packages installed at alongside the `sanity.blueprints.ts` configuration. You can even mix the two approaches, should your project require it. More details in the [Function dependencies](https://www.sanity.io/docs/functions/function-dependencies) docs.
### Blueprints
A function on its own doesn't know much about the larger Sanity ecosystem. That's where Blueprints come in. A blueprint is a template that describes Sanity resources. For Functions, blueprints describe when and where your function should trigger.
#### Learn more about Blueprints
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
### Event-driven workflow
Many Functions work on an event system. They react to changes in your data. Did an editor publish a new document? Run a function. Was a versioned document just updated? Run a function. Did someone just upload a new image to the Media Library that needs to kick off an approval workflow? Yep, run a function.
Functions support the following events:
- `create`: a new document is created.
- `update`: an existing document is modified.
- `delete`: an existing document is deleted.
You can learn more about document lifecycles in the [documents documentation](https://www.sanity.io/docs/content-lake/documents).
### Testing and logging
Your development process might need some adjustments to work with functions. As they run remotely on Sanity's infrastructure, you'll rely on local test commands and checking the logs from the CLI to debug your function logic.
Learn more about [testing your functions locally](https://www.sanity.io/docs/functions/functions-local-testing).
### Dependencies
It can be tempting to treat functions just like any other TS/JS project, but you should use restraint when including additional dependencies. See our guide on [structuring function dependencies in your projects](https://www.sanity.io/docs/functions/function-dependencies).
Additionally, prefer platform-agnostic packages in the JS ecosystem over libraries that wrap native code. This will help ensure your functions run as expected once deployed—regardless of your local environment.
### Deployment
You deploy functions as part of deploying a blueprint. You can learn more about deployment in the function quick starts, or use the [Blueprints GitHub Action](https://www.sanity.io/docs/blueprints/blueprint-action) to deploy them.
## Usage and cost considerations
### General costs
Functions use three variables when calculating cost.
- Invocations: The total number of times your function runs.
- Memory: The amount of memory a function uses to run. This defaults to 1GB, but you can adjust it up to 10GB in the blueprint configuration for each function.
- Duration: The execution time of the function.
Memory and duration combine to to give a GB-second calculation. For example, a function with 1GB of memory that runs for 2 seconds is 2GB-seconds. Multiply that by the number of total invocations, and you have your total GB-seconds.
As another example, if your functions average 1GB in memory-size and 40ms in duration, you could run 500k invocations to reach 20K GB-seconds.
Every function will be different, and your total usage accounts for all of your organization's functions. [Learn more on the pricing page](https://www.sanity.io/pricing).
### View your Functions usage
Functions usage is metered for the whole organization, not per project. To see it, go to [sanity.io/manage](https://www.sanity.io/manage), select the organization, and open the **Usage** tab. The figures are in the **Compute** section, which shows invocations and GB-seconds.
### API requests from functions
Invocations and compute time are metered separately from your project's API usage, but they do not replace it. Any request a function makes to the Content Lake counts toward the project's **API requests** or **API CDN requests** quota, the same as a request from any other client. Running inside Sanity's infrastructure does not exempt a function from those quotas.
To keep that usage down, read the document data from the incoming event payload instead of re-fetching the document that triggered the function, and use a GROQ projection to shape the payload so a second request is unnecessary.
### Scheduled Function frequency limits
Depending on your plan, you may experience limits to the number of actively scheduled functions you have, and how often they can run.
Each plan has a minimum threshold for how often a function can run
- Free: daily
- Growth: hourly
- Enterprise: minutely
For more details, [check your plan limits on the pricing page](https://www.sanity.io/pricing).
## Limitations
### Max function size
**Limit**: 200MB
Although your individual function's TypeScript or JavaScript code may appear small, it can rapidly expand in size when packages are included.
We strongly suggest keeping your functions small. The larger the function, the slower it is. You can limit the size, and therefore increase the execution speed by:
- Limit dependency usage to only what's necessary.
- Choose performant, slim libraries.
- If you must use large libraries, consider bundling or tree-shaking in advance.
If your functions require too many dependencies, it may help to narrow their purpose and split the logic into multiple functions.
### Max function execution time
Functions default to a max execution time of 10 seconds. In the [Blueprint configuration](https://www.sanity.io/docs/blueprints/blueprint-config), this can be configured from 1 to 900 seconds.
### Rate limits
To prevent accidental recursion and unexpected behaviors, we rate limit function executions.
**Per document**: If a function is invoked more than 200 times within 30 seconds in a single document, we stop further executions until the rate drops below the limit.
**Per project**: If functions from the same project are invoked more than 4000 times within 30 seconds, we stop further executions until the rate drops below the limit.
### Sync tag invalidate function limitation
To prevent race conditions and unexpected behavior, a dataset can only have a single sync tag invalidate function deployed.
If a dataset already has a sync tag invalidate function deployed, any attempt to deploy a blueprint that contains a sync tag invalidate function affecting the same dataset will return a `a sync tag invalidation subscription already exists` error.
### Function scope
When writing projections for a function, you’re limited to the invoking document’s scope. The exception being using `→` to follow references.
For example, projections containing a filter like shown below will fail silently:
**index.ts**
```groq
{
_id,
title,
specification {code},
"referencedBy": *[references(^._id)] {
_id,
title,
specification {code}
}
}
```
Instead, you’ll need to handle any nested filtering by making a new request inside the function. See our guide on [using the client library](https://www.sanity.io/docs/functions/functions-js-client) for more details.
# Create a Document Function
Functions allow you to run small, single-purpose code whenever your content in Sanity changes. This guide explains how to set up your project, initialize your first blueprint, add a function, and deploy it to Sanity's infrastructure.
Prerequisites:
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Node.js v24.x. We highly suggest working on this version as it is the same version that your functions will run when deployed to Sanity.
- An existing project and [a role with Deploy Studio permissions](https://www.sanity.io/docs/user-guides/roles) (the `deployStudio` grant).
> [!WARNING]
> Avoid recursive loops
> At this time, Sanity Functions limit recursive loops when using the `@sanity/client` v7.12.0 or later. Use caution when writing functions that may trigger themselves by editing other documents that trigger the function.
> Initiating multiple recursive functions may trigger [rate-limiting](https://www.sanity.io/docs/functions/functions-introduction) and may impact your usage limits sooner than expected. If you think you've deployed a recursive function or one that triggers too often, immediately override the deployment with new code, or `destroy` the blueprint.
## Set up your project
To create a function, you need to initialize a blueprint. Blueprints are templates that describe Sanity resources. In this case, a blueprint describes how your function will respond to updates in your Sanity project. We recommend keeping functions and blueprints a level above your Studio directory.
For example, if you have a Marketing Website that uses Sanity, you may have a structure like this:
```text
marketing-site/
├─ studio/
├─ next-app/
```
If you initialize the blueprint in the `marketing-site` directory, functions and future resources will live alongside the `studio` and `next-app` directory.
## Create a blueprint
Initialize your first blueprint with the `init` command. Replace with your project ID, found in manage or your sanity.config.ts file.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
This configures a new blueprint for your project, adds a `sanity.blueprint.ts` [config file](https://www.sanity.io/docs/blueprints/blueprint-config) to the current directory (`.`), and creates a new [stack](https://www.sanity.io/docs/blueprints/blueprints-introduction) named production.
Follow the prompt and run your package manager’s install command to add the dependencies.
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Create a function
Use the `sanity functions add` command to add a new function. You can also run it without any flags for interactive mode.
**npm**
```shell
npx sanity@latest functions add --name log-event --type document-create --type document-update --installer npm
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add --name log-event --type document-create --type document-update --installer npm
```
**yarn**
```shell
yarn dlx sanity@latest functions add --name log-event --type document-create --type document-update --installer npm
```
**bun**
```shell
bunx sanity@latest functions add --name log-event --type document-create --type document-update --installer npm
```
> [!TIP]
> If you’re using a package manager other than npm, set the `--installer` flag to your package manager, like `pnpm` or `yarn`. Run `sanity functions add --help` for more details.
After running the command, follow the prompt and add the function declaration to your `sanity.blueprint.ts` configuration. Your file should look like this:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({name: 'log-event', event: {on: ['create', 'update']}}),
],
})
```
The `on` property takes an array of trigger events:
- `create`: Fires when a new document is created for the first time.
- `update`: Fires when changes are made to an existing document.
- `delete`: Fires when a document is deleted.
For existing, published documents, `update` will only trigger when a draft or version is published and *updates* the document. In many cases where you'd use `update` on published documents, it may be better to use `['create', 'update']`. [Learn more about document lifecycles](https://www.sanity.io/docs/content-lake/documents).
This is the minimal configuration for defining a function in a blueprint file. You can see all available options in the [Function section of the Blueprints configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config).
If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:
```text
marketing-site/
├─ studio/
├─ next-app/
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
├─ functions/
│ ├─ log-event/
│ │ ├─ index.ts
```
After updating the `sanity.blueprint.ts` file, open `functions/log-event/index.ts` in your editor.
> [!TIP]
> The documentEventHandler function
> TypeScript functions can take advantage of the `documentEventHandler` helper function to provide type support. Examples in this article include both TypeScript and JavaScript function syntax.
Every function exports a `handler` from the index file.
**functions/log-event/index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
})
```
**functions/log-event/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
}
```
The handler receives a `context` and an `event`. The context contains information to help you interact with your Sanity datastore, such as `clientOptions` to configure a `@sanity/client`.
The `event` contains information about the action that triggered the function. Most functions will use `event.data`, which contains the contents of the Sanity document. You can learn more in the [Function handler reference](https://www.sanity.io/docs/functions/function-wrapper).
### Limit the scope with GROQ
This function will run every time any document publishes and return the entire document to `event.data`. This includes system documents. Let’s narrow the scope.
Open the `sanity.blueprint.ts` file and update it to include an `event` object with the `on` and `filter` properties:
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: 'log-event',
event: {
on: ['create', 'update'],
filter: '_type == "post"'
}
}),
],
})
```
`filter` accepts a [GROQ filter](https://www.sanity.io/docs/specifications/groq-syntax) that limits which documents will trigger the function. Only include the filter contents, *the portion inside the square brackets*, of your GROQ query. For example, rather than `*[_type == 'post']`, only include `_type == 'post'`.
Projections let you shape the contents passed to the event. Set the `projection` property on `event`. If you want your function to receive an object instead of individual attributes, ensure your `projection` is wrapped in curly braces (`{}`) as shown in the example.
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: 'log-event',
event: {
on: ['create', 'update'],
filter: '_type == "post"',
projection: "{_id, content}"
}
}),
],
})
```
Projections don't limit what fields trigger the function, only which data is passed into the function.
GROQ is a powerful query language, and with features such as [delta functions](https://www.sanity.io/docs/specifications/groq-functions) —to help you determine *what* in a document changed as well as *how* it changed—you can narrow the scope even farther. Check out the [GROQ Query Cheat Sheet](https://www.sanity.io/docs/content-lake/query-cheat-sheet) for more ideas, and the [Functions cheat sheet](https://www.sanity.io/docs/functions/functions-cheatsheet) for additional function-specific techniques.
### Limit to a specific dataset
Functions will run against all of a project’s datasets by default. We recommend scoping a function to your desired dataset. Use the `projectId.datasetName` format as the resource ID in the `event`.
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: 'log-event',
event: {
on: ['create', 'update'],
filter: '_type == "post"',
projection: "{_id, content}",
resource: {
type: 'dataset',
id: 'myProjectId.production'
}
}
}),
],
})
```
## Test the function locally
You can test functions locally with the functions development playground. Local testing is a great way to experiment without affecting your usage quota.
To launch the development playground, run the following:
**npm**
```shell
npx sanity functions dev
```
**pnpm**
```shell
pnpm dlx sanity functions dev
```
**yarn**
```shell
yarn dlx sanity functions dev
```
**bun**
```shell
bunx sanity functions dev
```
If you run this on the starter function from earlier, you'll see the default output message in the console pane.
To test with real data from your project, you can pass a document `_id` and select a project/dataset to fetch a document and pass it to the function's `event`. Don't forget to press the download button next to the document ID to populate the input. You can also manually enter a document-like shape. In either case, make sure it matches your projection criteria.
Update your function to log the `event` and you'll see the supplied document details the next time you run the function in the playground.
**functions/log-event/index.ts (TypeScript)**
```typescript
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
})
```
**functions/log-event/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
}
```
> [!TIP]
> Development playground
> In addition to the `sanity functions dev` command, there's also a more traditional CLI testing interface.
> Run the `sanity functions test functionName` command to run the function locally. You can learn more in the [local testing guide](https://www.sanity.io/docs/functions/functions-local-testing) and the [functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Deploy a function
Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
You can begin using your function when the deployment finishes. If you set a filter earlier, edit a document that matches it and publish the changes to trigger the function.
If you need to change the function, update your code and re-run the deploy command to push the new changes live.
## Check the logs
When you tested the function locally, you saw the logs directly in your console. Once deployed, the function and its logs are in the cloud.
View the logs with the `functions logs` command. Replace `log-event` with your function name.
**npm**
```shell
npx sanity functions logs log-event
```
**pnpm**
```shell
pnpm dlx sanity functions logs log-event
```
**yarn**
```shell
yarn dlx sanity functions logs log-event
```
**bun**
```shell
bunx sanity functions logs log-event
```
This command outputs the function's logs. Try updating your document, publishing the change, and running the command again to see new logs.
> [!NOTE]
> System documents
> If you didn't limit the scope of the function by setting a GROQ filter earlier, every change to a published document will run the function. This can greatly increase your usage, so it's best to create specific filters for your documents.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
# Create a Media Library Asset Function
Media Library Asset Functions allow you to run small, single-purpose code whenever a Media Library `sanity.asset` document changes. These are the [container documents that hold basic metadata, versions, and aspect data](https://www.sanity.io/docs/content-lake/document-reference).
You can try things like:
- Compare changes in an asset's aspect data.
- Kick off a review flow when new versions are added to an asset.
- Update references when assets are deleted.
This guide explains how to set up your project, initialize your first blueprint, add a function, and deploy it to Sanity's infrastructure.
Prerequisites:
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Node.js v24.x. We highly suggest working on this version as it is the same version that your functions will run when deployed to Sanity.
- An existing project and [a role with Deploy Studio permissions](https://www.sanity.io/docs/user-guides/roles) (the `deployStudio` grant).
> [!WARNING]
> Avoid recursive loops
> At this time, Sanity Functions limit recursive loops when using the `@sanity/client` v7.12.0 or later. Use caution when writing functions that may trigger themselves by editing other documents that trigger the function.
> Initiating multiple recursive functions may trigger [rate-limiting](https://www.sanity.io/docs/functions/functions-introduction) and may impact your usage limits sooner than expected. If you think you've deployed a recursive function or one that triggers too often, immediately override the deployment with new code, or `destroy` the blueprint.
## Set up your project
To create a function, you need to initialize a blueprint. Blueprints are templates that describe Sanity resources. In this case, a blueprint describes how your function will respond to updates in your Sanity project. We recommend keeping functions and blueprints a level above your Studio directory.
For example, if you have a Marketing Website that uses Sanity, you may have a structure like this:
```text
marketing-site/
├─ studio/
├─ next-app/
```
If you initialize the blueprint in the `marketing-site` directory, functions and future resources will live alongside the `studio` and `next-app` directory.
## Create a blueprint
Initialize your first blueprint with the `init` command. Replace with your project ID, found in manage or your sanity.config.ts file.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
This configures a new blueprint for your project, adds a `sanity.blueprint.ts` [config file](https://www.sanity.io/docs/blueprints/blueprint-config) to the current directory (`.`), and creates a new [stack](https://www.sanity.io/docs/blueprints/blueprints-introduction) named production.
Follow the prompt and run your package manager’s install command to add the dependencies.
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Create a function
Use the `sanity functions add` command to add a new function. You can also run it without any flags for interactive mode.
**npm**
```shell
npx sanity@latest functions add --name asset-update --type media-library-asset-create --type media-library-asset-update --installer npm
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add --name asset-update --type media-library-asset-create --type media-library-asset-update --installer npm
```
**yarn**
```shell
yarn dlx sanity@latest functions add --name asset-update --type media-library-asset-create --type media-library-asset-update --installer npm
```
**bun**
```shell
bunx sanity@latest functions add --name asset-update --type media-library-asset-create --type media-library-asset-update --installer npm
```
> [!TIP]
> If you’re using a package manager other than npm, set the `--installer` flag to your package manager, like `pnpm` or `yarn`. Run `sanity functions add --help` for more details.
After running the command, follow the prompt and add the function declaration to your `sanity.blueprint.ts` configuration. Your file should look like this:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineMediaLibraryAssetFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineMediaLibraryAssetFunction({
name: 'asset-update',
event: {
on: ['create', 'update'],
resource: {type: 'media-library', id: 'my-media-library-id'}
}
})
],
})
```
Replace `my-media-library-id` with your [Media Library ID](https://www.sanity.io/docs/media-library/configure-library).
The `on` property is already set and takes an array of trigger events:
- `create`: Fires when a new document is created for the first time.
- `update`: Fires when changes are made to an existing document.
- `delete`: Fires when an asset document is deleted.
For existing, published documents, `update` will only trigger when a draft is published and *updates* the document. In many cases where you'd use `update` on published documents, it may be better to use `['create', 'update']` to ensure new documents also trigger the function. [Learn more about document lifecycles](https://www.sanity.io/docs/content-lake/documents).
This is the minimal configuration for defining a Media Library Asset Function in a blueprint file. You can see all available options in the [Function section of the Blueprints configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config).
If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:
```text
marketing-site/
├─ studio/
├─ next-app/
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
├─ functions/
│ ├─ asset-update/
│ │ ├─ index.ts
```
After updating the `sanity.blueprint.ts` file, open `functions/asset-update/index.ts` in your editor.
> [!TIP]
> The documentEventHandler function
> TypeScript functions can take advantage of the `documentEventHandler` helper function to provide type support. Examples in this article include both TypeScript and JavaScript function syntax.
Every function exports a `handler` from the index file.
**functions/asset-update/index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
})
```
**functions/asset-update/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
}
```
The handler receives a `context` and an `event`. The context contains information to help you interact with your Sanity datastore, such as `clientOptions` to configure a `@sanity/client`.
The `event` contains information about the action that triggered the function. Most functions will use `event.data`, which contains the contents of the Sanity document. You can learn more in the [Function handler reference](https://www.sanity.io/docs/functions/function-wrapper).
### Limit the scope with GROQ
This function will run every time any Media Library asset documents (documents with a `_type` of `sanity.asset`) change and it will return the entire document to `event.data`. Let’s narrow the scope by writing a GROQ filter.
#### Filters
Open the `sanity.blueprint.ts` file and add a `filter` to the `event` object:
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineMediaLibraryAssetFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineMediaLibraryAssetFunction({
name: 'asset-update',
event: {
on: ['create', 'update'],
resource: {type: 'media-library', id: 'my-media-library-id'},
filter: 'cdnAccessPolicy == "private"',
}
})
],
})
```
This filter causes the function to only run when private assets are created or updated.
`filter` accepts a [GROQ filter](https://www.sanity.io/docs/specifications/groq-syntax) that limits which documents will trigger the function. Only include the filter contents, *the portion inside the square brackets*, of your GROQ query. For example, rather than `*[cdnAccessPolicy == 'private']`, only include `cdnAccessPolicy == 'post'`.
#### Projections
Projections let you shape the contents passed to the event. Set the `projection` property on `event`. If you want your function to receive an object instead of individual attributes, ensure your `projection` is wrapped in curly braces (`{}`) as shown in the example.
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineMediaLibraryAssetFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineMediaLibraryAssetFunction({
name: 'asset-update',
event: {
on: ['create', 'update'],
resource: {type: 'media-library', id: 'my-media-library-id'},
filter: 'cdnAccessPolicy == "private"',
projection: '{_id, aspects, currentVersion, title, url}'
}
})
],
})
```
Projections don't limit what fields trigger the function, only which data is passed into the function.
GROQ is a powerful query language, and with features such as [delta functions](https://www.sanity.io/docs/specifications/groq-functions) —to help you determine *what* in a document changed as well as *how* it changed—you can narrow the scope even farther. Check out the [GROQ Query Cheat Sheet](https://www.sanity.io/docs/content-lake/query-cheat-sheet) for more ideas, and the [Functions cheat sheet](https://www.sanity.io/docs/functions/functions-cheatsheet) for additional function-specific techniques.
## Test the function locally
You can test functions locally with the functions development playground. Local testing is a great way to experiment without affecting your usage quota.
To launch the development playground, run the following:
**npm**
```shell
npx sanity functions dev
```
**pnpm**
```shell
pnpm dlx sanity functions dev
```
**yarn**
```shell
yarn dlx sanity functions dev
```
**bun**
```shell
bunx sanity functions dev
```
If you run this on the starter function from earlier, you'll see the default output message in the console pane.
To test with real data from your Media Library, you can pass a document `_id` and select your library ID to fetch an asset document and pass it to the function's `event`. Don't forget to press the download button next to the document ID to populate the input. You can also manually enter a document-like shape. In either case, make sure it matches your projection criteria.
Update your function to log the `event` and you'll see the supplied document details the next time you run the function in the playground.
**functions/asset-update/index.ts (TypeScript)**
```typescript
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
})
```
**functions/asset-update/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
}
```
> [!TIP]
> Development playground
> In addition to the `sanity functions dev` command, there's also a more traditional CLI testing interface.
> Run the `sanity functions test functionName` command to run the function locally. You can learn more in the [local testing guide](https://www.sanity.io/docs/functions/functions-local-testing) and the [functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Deploy a function
Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
You can begin using your function when the deployment finishes. If you set a filter earlier, edit a document that matches it and publish the changes to trigger the function.
If you need to change the function, update your code and re-run the deploy command to push the new changes live.
## Check the logs
When you tested the function locally, you saw the logs directly in your console. Once deployed, the function and its logs are in the cloud.
View the logs with the `functions logs` command. Replace `asset-update` with your function name.
**npm**
```shell
npx sanity functions logs asset-update
```
**pnpm**
```shell
pnpm dlx sanity functions logs asset-update
```
**yarn**
```shell
yarn dlx sanity functions logs asset-update
```
**bun**
```shell
bunx sanity functions logs asset-update
```
This command outputs the function's logs. Try updating your document, publishing the change, and running the command again to see new logs.
> [!NOTE]
> System documents
> If you didn't limit the scope of the function by setting a GROQ filter earlier, every change to a published document will run the function. This can greatly increase your usage, so it's best to create specific filters for your documents.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
# Create a Sync Tag Invalidate Function
Sync Tag Invalidate Functions allow you to run small, single-purpose code whenever your updated content is ready for querying. This guide explains how to set up your project, initialize your first blueprint, add a function, and deploy it to Sanity's infrastructure.
> [!WARNING]
> Avoid deploying multiple sync-tag-invalidate functions per dataset
> Having multiple `sync-tag-invalidate` functions set up for a single dataset may lead to race conditions, unexpected results, or increased usage.
> We recommend scoping your `sync-tag-invalidate` function to a specific dataset as shown below, or see the Function `event` [Blueprint configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config) for more configuration options.
Prerequisites:
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Node.js v24.x. We highly suggest working on this version as it is the same version that your functions will run when deployed to Sanity.
- An existing project and [a role with Deploy Studio permissions](https://www.sanity.io/docs/user-guides/roles) (the `deployStudio` grant).
> [!WARNING]
> Avoid recursive loops
> At this time, Sanity Functions limit recursive loops when using the `@sanity/client` v7.12.0 or later. Use caution when writing functions that may trigger themselves by editing other documents that trigger the function.
> Initiating multiple recursive functions may trigger [rate-limiting](https://www.sanity.io/docs/functions/functions-introduction) and may impact your usage limits sooner than expected. If you think you've deployed a recursive function or one that triggers too often, immediately override the deployment with new code, or `destroy` the blueprint.
If you’ve previously created a project, you can skip ahead to [Add a Sync Tag Invalidate function](https://www.sanity.io/docs/functions/sync-tag-function-quickstart).
## Set up your project
To create a function, you need to initialize a blueprint. Blueprints are templates that describe Sanity resources. In this case, a blueprint describes how your function will respond to updates in your Sanity project. We recommend keeping functions and blueprints a level above your Studio directory.
For example, if you have a Marketing Website that uses Sanity, you may have a structure like this:
```text
marketing-site/
├─ studio/
├─ next-app/
```
If you initialize the blueprint in the `marketing-site` directory, functions and future resources will live alongside the `studio` and `next-app` directory.
## Create a blueprint
Initialize your first blueprint with the `init` command. Replace with your project ID, found in manage or your sanity.config.ts file.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
This configures a new blueprint for your project, adds a `sanity.blueprint.ts` [config file](https://www.sanity.io/docs/blueprints/blueprint-config) to the current directory (`.`), and creates a new [stack](https://www.sanity.io/docs/blueprints/blueprints-introduction) named production.
Follow the prompt and run your package manager’s install command to add the dependencies.
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Add a Sync Tag Invalidate function
Use the `sanity functions add` command to add a new function. You can also run it without any flags for interactive mode.
**npm**
```shell
npx sanity@latest functions add --name invalidate-tags --type sync-tag-invalidate --installer npm
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add --name invalidate-tags --type sync-tag-invalidate --installer npm
```
**yarn**
```shell
yarn dlx sanity@latest functions add --name invalidate-tags --type sync-tag-invalidate --installer npm
```
**bun**
```shell
bunx sanity@latest functions add --name invalidate-tags --type sync-tag-invalidate --installer npm
```
> [!TIP]
> If you’re using a package manager other than npm, set the `--installer` flag to your package manager, like `pnpm` or `yarn`. Run `sanity functions add --help` for more details.
After running the command, follow the prompt and add the function declaration to your `sanity.blueprint.ts` configuration. Your file should look like this:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineSyncTagInvalidateFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineSyncTagInvalidateFunction({name: 'invalidate-tags'}),
],
})
```
By default, your new function will receive sync tag invalidation events for *all* datasets in your project. We recommend you add an `event` to your function definition with a `resource` scoping your function to a particular dataset.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineSyncTagInvalidateFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineSyncTagInvalidateFunction({
name: "invalidate-tags",
event: {
resource: {
type: 'dataset',
id: 'myProjectId.myProductionDataset'
}
}
})
],
})
```
You can see all available options in the [Function section of the Blueprints configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config).
If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:
```text
marketing-site/
├─ studio/
├─ next-app/
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
├─ functions/
│ ├─ invalidate-tags/
│ │ ├─ index.ts
```
After updating the `sanity.blueprint.ts` file, open `functions/invalidate-tags/index.ts` in your editor.
> [!TIP]
> The syncTagInvalidateEventHandler function
> TypeScript functions can take advantage of the `syncTagInvalidateEventHandler` helper function to provide type support. Examples in this article include both TypeScript and JavaScript function syntax.
Every function exports a `handler` from the index file.
**functions/invalidate-tags/index.ts (TypeScript)**
```
import { syncTagInvalidateEventHandler } from '@sanity/functions'
export const handler = syncTagInvalidateEventHandler(async ({ context, event, done }) => {
const time = new Date().toLocaleTimeString()
console.log(`Your sync tag invalidate Sanity Function was called at ${time}`)
// TODO: add code to do something with the invalidated sync tags provided to you in `event.data.syncTags`
try {
// notify Sanity that you have completed invalidation
const response = await done(event.data.syncTags)
console.log('Invalidation complete, Sanity responded with an HTTP', response.status)
} catch (e) {
console.error('Error invoking Sanity invalidation done endpoint!', e)
}
})
```
**functions/invalidate-tags/index.js (JavaScript)**
```javascript
import { syncTagInvalidateEventHandler } from '@sanity/functions'
export const handler = syncTagInvalidateEventHandler(async ({ context, event, done }) => {
const time = new Date().toLocaleTimeString()
console.log(`Your sync tag invalidate Sanity Function was called at ${time}`)
// TODO: add code to do something with the invalidated sync tags provided to you in `event.data.syncTags`
try {
// notify Sanity that you have completed invalidation
const response = await done(event.data.syncTags)
console.log('Invalidation complete, Sanity responded with an HTTP', response.status)
} catch (e) {
console.error('Error invoking Sanity invalidation done endpoint!', e)
}
})
```
The handler receives a `context`, an `event` and a `done` callback.
The `event` contains the sync tags that were invalidated, available at `event.data.syncTags`. You can learn more in the [Function handler reference](https://www.sanity.io/docs/functions/function-wrapper).
The `done` callback is an asynchronous method issuing an HTTP request back to Sanity, notifying us that you have completed your invalidation routine. It is a thin wrapper around native node.js `fetch`, returning a fetch `Response`.
> [!WARNING]
> Your function must notify Sanity that your invalidation routine is complete by invoking the `done` callback. Calling `done` is what releases the invalidation to clients subscribed to the [Live Content API](https://www.sanity.io/docs/content-lake/live-content-api) with `waitFor=function`. With that parameter set, Sanity holds these sync tag events back until your function has processed them, so if `done` never completes, those clients won't receive the change, leading to unexpected Live Content behavior. It is your responsibility to confirm the callback completed successfully, so we recommend wrapping the `done` invocation in a `try/catch` and logging any failures.
## Test the function locally
You can test functions locally with the functions development playground. Local testing is a great way to experiment without affecting your usage quota.
To launch the development playground, run the following:
**npm**
```shell
npx sanity functions dev
```
**pnpm**
```shell
pnpm dlx sanity functions dev
```
**yarn**
```shell
yarn dlx sanity functions dev
```
**bun**
```shell
bunx sanity functions dev
```
If you run this on the starter function from earlier, you'll see the default output message in the console pane.
Select your new Sync Tag Invalidate function from the list on the left. Note that the Sync Tag Payload panel is populated with a dummy sync tag invalidate event shape that your function can use as a test payload.
Click the Run button at the bottom, and you should see the starter Sync Tag Invalidate function template code output its logs to the Console panel:
**console**
```text
4/10/2026 9:14:52 AM INFO Your sync tag invalidate Sanity Function was called at 9:14:52 AM
4/10/2026 9:14:52 AM INFO Invalidation complete, Sanity responded with an HTTP 204
```
> [!TIP]
> Development playground
> In addition to the `sanity functions dev` command, there's also a more traditional CLI testing interface.
> Run the `sanity functions test functionName` command to run the function locally. You can learn more in the [local testing guide](https://www.sanity.io/docs/functions/functions-local-testing) and the [functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Deploy a function
Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
You can begin using your function when the deployment finishes. Edit a document in a dataset and publish the changes to trigger the function.
If you need to change the function, update your code and re-run the deploy command to push the new changes live.
## Check the logs
When you tested the function locally, you saw the logs directly in your console. Once deployed, the function and its logs are in the cloud.
View the logs with the `functions logs` command. Replace `invalidate-tags` with your function name.
**npm**
```shell
npx sanity functions logs invalidate-tags
```
**pnpm**
```shell
pnpm dlx sanity functions logs invalidate-tags
```
**yarn**
```shell
yarn dlx sanity functions logs invalidate-tags
```
**bun**
```shell
bunx sanity functions logs invalidate-tags
```
This command outputs the function's logs. Try updating your document, publishing the change, and running the command again to see new logs.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
# Create a Scheduled Function
Functions allow you to run small, single-purpose code whenever your content in Sanity changes. This guide explains how to set up your project, initialize your first blueprint, add a function, and deploy it to Sanity's infrastructure.
Prerequisites:
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Node.js v24.x. We highly suggest working on this version as it is the same version that your functions will run when deployed to Sanity.
- Different plans offer different function cadence limits. Check the [Functions pricing section](https://www.sanity.io/docs/functions/functions-introduction) for more details.
- **If you’re using an existing blueprint**, it needs to use an [organization-scoped](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope) stack.
- Deploying an organization-scoped stack requires the organization admin role, the new blueprint deployer role, or a [robot token](https://www.sanity.io/docs/content-lake/http-auth) with the `sanity.blueprints.deploy` permission.
If you’ve previously set up your project and added functions, skip ahead to the [Add a scheduled function](https://www.sanity.io/docs/functions/scheduled-function-quickstart) section.
## Set up your project
To create a function, you need to initialize a blueprint. Blueprints are templates that describe Sanity resources. In this case, a blueprint describes when your function will run. We recommend keeping functions and blueprints a level above your Studio directory.
For example, if you have a Marketing Website that uses Sanity, you may have a structure like this:
```text
marketing-site/
├─ studio/
├─ next-app/
```
If you initialize the blueprint in the `marketing-site` directory, functions and future resources will live alongside the `studio` and `next-app` directory.
## Create a blueprint
Initialize your first blueprint with the `init` command. Replace with your organization ID, found in [manage](https://www.sanity.io/manage).
**npm**
```shell
npx sanity@latest blueprints init . --type ts --stack-name production --organization-id
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --stack-name production --organization-id
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --stack-name production --organization-id
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --stack-name production --organization-id
```
This configures an [organization-scoped blueprint stack](https://www.sanity.io/docs/blueprints/promote-stack-to-organization-scope), adds a `sanity.blueprint.ts` [config file](https://www.sanity.io/docs/blueprints/blueprint-config) to the current directory (`.`), and creates a new [stack](https://www.sanity.io/docs/blueprints/blueprints-introduction) named production.
Follow the prompt and run your package manager’s install command to add the dependencies.
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Add a scheduled function
Use the `sanity functions add` command to add a new function. You can also run it without any flags for interactive mode.
**npm**
```shell
npx sanity@latest functions add --name expire-cache --type scheduled-function --language ts --installer npm
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add --name expire-cache --type scheduled-function --language ts --installer npm
```
**yarn**
```shell
yarn dlx sanity@latest functions add --name expire-cache --type scheduled-function --language ts --installer npm
```
**bun**
```shell
bunx sanity@latest functions add --name expire-cache --type scheduled-function --language ts --installer npm
```
> [!TIP]
> If you’re using a package manager other than npm, set the `--installer` flag to your package manager, like `pnpm` or `yarn`. Run `sanity functions add --help` for more details.
After running the command, follow the prompt and add the function declaration to your `sanity.blueprint.ts` configuration. Your file should look like this:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineScheduledFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineScheduledFunction({name: 'expire-cache', event: {expression: '0 0 * * *'}}),
],
})
```
This is the minimal configuration for defining a function in a blueprint file. You can see all available options in the [Function section of the Blueprints configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config).
If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:
```text
marketing-site/
├─ studio/
├─ next-app/
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
├─ functions/
│ ├─ expire-cache/
│ │ ├─ index.ts
```
After updating the `sanity.blueprint.ts` file, open `functions/expire-cache/index.ts` in your editor.
> [!TIP]
> The scheduledEventHandler function
> TypeScript functions can take advantage of the `scheduledEventHandler` helper function to provide type support. Examples in this article include both TypeScript and JavaScript function syntax.
Every function exports a `handler` from the index file.
**functions/expire-cache/index.ts (TypeScript)**
```
import { scheduledEventHandler } from '@sanity/functions'
export const handler = scheduledEventHandler(async ({ context }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
})
```
**functions/expire-cache/index.js (JavaScript)**
```javascript
export async function handler({context}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
}
```
If you plan to interact with a Sanity project’s dataset from your scheduled function, you can [install the Sanity client](https://www.sanity.io/docs/functions/functions-js-client) and configure it. As scheduled functions are organization-scoped, they don’t have a project and dataset in their `context`. You need to explicitly [define a robot token](https://www.sanity.io/docs/functions/robot-tokens-with-functions) and set the projectId and dataset when configuring the client.
Create the robot token in your blueprint and reference it from the scheduled function definer:
**sanity.blueprint.ts**
```
import { defineBlueprint, defineScheduledFunction, defineRobotToken } from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'my-robot',
label: 'My Robot',
memberships: [
{
resourceType: 'project',
resourceId: 'abc123',
roleNames: ['editor'],
},
],
}),
defineScheduledFunction({
name: 'expire-cache',
event: {expression: '0 0 * * *'},
robotToken: '$.resources.my-robot.token',
}),
],
})
```
Configure the client:
**index.ts**
```
import { scheduledEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = scheduledEventHandler(async ({ context }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
const client = createClient({
projectId: 'YOUR_PROJECT_ID',
dataset: 'YOUR_DATASET',
apiVersion: '2026-04-29',
token: context.clientOptions?.token,
})
})
```
## Set a schedule
Scheduled function events can use the universal, but often difficult to read, [UNIX Cron Expression](https://www.ibm.com/docs/en/db2-as-a-service?topic=task-unix-cron-format) format. To make it easier to understand when your function will run we also support an explicit event format.
**Explicit format**
```
import {defineBlueprint, defineScheduledFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineScheduledFunction({
name: 'expire-cache',
event: {
minute: '0',
hour: '0',
dayOfMonth: '*',
month: '*',
dayOfWeek: '*',
}
}),
],
})
```
**CRON format**
```
import {defineBlueprint, defineScheduledFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineScheduledFunction({
name: 'expire-cache',
event: {
expression: '0 0 * * *',
}
}),
],
})
```
While this format is more verbose, it is easier to read that this function will run at midnight UTC every day of the year.
### Set a timezone (optional)
In order to give you better control over exactly when you function executes you can provide a timezone property to your schedule function.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineScheduledFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineScheduledFunction({
name: 'expire-cache',
event: {
minute: '0',
hour: '0',
dayOfMonth: '*',
month: '*',
dayOfWeek: '*',
},
timezone: 'America/New_York'
}),
],
})
```
The `timezone` property supports an [IANA time zone identifier](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones), such as `America/New_York` or `Europe/Berlin`. If a timezone isn’t set, the schedule defaults to UTC.
## Test the function locally
You can test functions locally with the functions development playground. Local testing is a great way to experiment without affecting your usage quota.
To launch the development playground, run the following:
**npm**
```shell
npx sanity functions dev
```
**pnpm**
```shell
pnpm dlx sanity functions dev
```
**yarn**
```shell
yarn dlx sanity functions dev
```
**bun**
```shell
bunx sanity functions dev
```
If you run this on the starter function from earlier, you'll see the default output message in the console pane.
> [!TIP]
> Development playground
> In addition to the `sanity functions dev` command, there's also a more traditional CLI testing interface.
> Run the `sanity functions test functionName` command to run the function locally. You can learn more in the [local testing guide](https://www.sanity.io/docs/functions/functions-local-testing) and the [functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Deploy the blueprint
Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
You can begin using your function when the deployment finishes. In the case of scheduled functions, you’ll need to wait for the event interval for it to run.
If you need to change the function, update your code and re-run the deploy command to push the new changes live.
## Check the logs
When you tested the function locally, you saw the logs directly in your console. Once deployed, the function and its logs are in the cloud.
View the logs with the `functions logs` command. Replace `expire-cache` with your function name.
**npm**
```shell
npx sanity functions logs expire-cache
```
**pnpm**
```shell
pnpm dlx sanity functions logs expire-cache
```
**yarn**
```shell
yarn dlx sanity functions logs expire-cache
```
**bun**
```shell
bunx sanity functions logs expire-cache
```
This command outputs the function's logs. Run the command again after the scheduled interval passes to see new logs.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
# Create a PubSub function
Functions allow you to run small, single-purpose code whenever your content in Sanity changes. This guide explains how to set up your project, initialize your first blueprint, add a function, and deploy it to Sanity's infrastructure.
Prerequisites:
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Node.js v24.x. We highly suggest working on this version as it is the same version that your functions will run when deployed to Sanity.
- An existing project and [a role with Deploy Studio permissions](https://www.sanity.io/docs/user-guides/roles) (the `deployStudio` grant).
> [!WARNING]
> Avoid recursive loops
> At this time, Sanity Functions limit recursive loops when using the `@sanity/client` v7.12.0 or later. Use caution when writing functions that may trigger themselves by editing other documents that trigger the function.
> Initiating multiple recursive functions may trigger [rate-limiting](https://www.sanity.io/docs/functions/functions-introduction) and may impact your usage limits sooner than expected. If you think you've deployed a recursive function or one that triggers too often, immediately override the deployment with new code, or `destroy` the blueprint.
## Set up your project
To create a function, you need to initialize a blueprint. Blueprints are templates that describe Sanity resources. In this case, a blueprint describes how your function will respond to updates in your Sanity project. We recommend keeping functions and blueprints a level above your Studio directory.
For example, if you have a Marketing Website that uses Sanity, you may have a structure like this:
```text
marketing-site/
├─ studio/
├─ next-app/
```
If you initialize the blueprint in the `marketing-site` directory, functions and future resources will live alongside the `studio` and `next-app` directory.
## Create a blueprint
Initialize your first blueprint with the `init` command. Replace with your project ID, found in manage or your sanity.config.ts file.
**npm**
```shell
npx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
**bun**
```shell
bunx sanity@latest blueprints init . --type ts --stack-name production --project-id
```
This configures a new blueprint for your project, adds a `sanity.blueprint.ts` [config file](https://www.sanity.io/docs/blueprints/blueprint-config) to the current directory (`.`), and creates a new [stack](https://www.sanity.io/docs/blueprints/blueprints-introduction) named production.
Follow the prompt and run your package manager’s install command to add the dependencies.
**npm**
```shell
npm install
```
**pnpm**
```shell
pnpm install
```
**yarn**
```shell
yarn install
```
**bun**
```shell
bun install
```
## Create a function
Use the `sanity functions add` command to add a new function. You can also run it without any flags for interactive mode.
**npm**
```shell
npx sanity@latest functions add --name slack-post --type pub-sub --installer npm
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add --name slack-post --type pub-sub --installer npm
```
**yarn**
```shell
yarn dlx sanity@latest functions add --name slack-post --type pub-sub --installer npm
```
**bun**
```shell
bunx sanity@latest functions add --name slack-post --type pub-sub --installer npm
```
> [!TIP]
> If you’re using a package manager other than npm, set the `--installer` flag to your package manager, like `pnpm` or `yarn`. Run `sanity functions add --help` for more details.
After running the command, follow the prompt and add the function declaration to your `sanity.blueprint.ts` configuration. Your file should look like this:
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, definePubSubFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
definePubSubFunction({name: 'slack-post'}),
],
})
```
This is the minimal configuration for defining a function in a blueprint file. You can see all available options in the [Function section of the Blueprints configuration reference documentation](https://www.sanity.io/docs/blueprints/blueprint-config).
If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:
```text
marketing-site/
├─ studio/
├─ next-app/
├─ sanity.blueprint.ts
├─ package.json
├─ node_modules/
├─ functions/
│ ├─ slack-post/
│ │ ├─ index.ts
```
After updating the `sanity.blueprint.ts` file, open `functions/slack-post/index.ts` in your editor.
> [!TIP]
> The pubSubEventHandler function
> TypeScript functions can take advantage of the `pubSubEventHandler` helper function to provide type support. Examples in this article include both TypeScript and JavaScript function syntax.
Every function exports a `handler` from the index file.
**functions/slack-post/index.ts (TypeScript)**
```typescript
import { pubSubEventHandler } from '@sanity/functions'
export const handler = pubSubEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
})
```
**functions/slack-post/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
}
```
The handler receives a `context` and an `event`. The `context` contains information to help you interact with your Sanity datastore, such as `clientOptions` to configure a `@sanity/client`.
The `event` contains information about the action that triggered the function. Most functions will use `event.data`. You can learn more in the [Function handler reference](https://www.sanity.io/docs/functions/function-wrapper).
## Test the function locally
You can test functions locally with the functions development playground. Local testing is a great way to experiment without affecting your usage quota.
To launch the development playground, run the following:
**npm**
```shell
npx sanity functions dev
```
**pnpm**
```shell
pnpm dlx sanity functions dev
```
**yarn**
```shell
yarn dlx sanity functions dev
```
**bun**
```shell
bunx sanity functions dev
```
If you run this on the starter function from earlier, you'll see the default output message in the console pane.
Update your function to log the `event` and you'll see the supplied document details the next time you run the function in the playground.
**functions/slack-post/index.ts (TypeScript)**
```typescript
import { pubSubEventHandler } from '@sanity/functions'
export const handler = pubSubEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
})
```
**functions/slack-post/index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
console.log('Event:', event)
}
```
> [!TIP]
> Development playground
> In addition to the `sanity functions dev` command, there's also a more traditional CLI testing interface.
> Run the `sanity functions test functionName` command to run the function locally. You can learn more in the [local testing guide](https://www.sanity.io/docs/functions/functions-local-testing) and the [functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Deploy a function
Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.
**npm**
```shell
npx sanity blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity blueprints deploy
```
**yarn**
```shell
yarn dlx sanity blueprints deploy
```
**bun**
```shell
bunx sanity blueprints deploy
```
You can begin using your function when the deployment finishes. Learn more about [invoking PubSub Functions](https://www.sanity.io/docs/functions/function-to-function-invocation).
If you need to change the function, update your code and re-run the deploy command to push the new changes live.
## Check the logs
When you tested the function locally, you saw the logs directly in your console. Once deployed, the function and its logs are in the cloud.
View the logs with the `functions logs` command. Replace `log-event` with your function name.
**npm**
```shell
npx sanity functions logs slack-post
```
**pnpm**
```shell
pnpm dlx sanity functions logs slack-post
```
**yarn**
```shell
yarn dlx sanity functions logs slack-post
```
**bun**
```shell
bunx sanity functions logs slack-post
```
This command outputs the function's logs. Try updating your document, publishing the change, and running the command again to see new logs.
## Destroy a deployed blueprint
Sometimes you want to remove a deployed resource so it won't run anymore or affect any future usage quotas.
To remove a resources created with a blueprint, you need to either:
1. Remove the definition from the blueprint, and run the `deploy` command again.
2. Destroy the blueprint with the `destroy` command.
The `blueprints destroy` command removes, or undeploys*,* the blueprint and all of its resources from Sanity's infrastructure. It does not remove your local files.
**npm**
```shell
npx sanity blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity blueprints destroy
```
**yarn**
```shell
yarn dlx sanity blueprints destroy
```
**bun**
```shell
bunx sanity blueprints destroy
```
To remove the resource from the blueprint locally, you can remove it from the `resources` array in the `sanity.blueprint.ts` file, then delete any associated files.
### Redeploying a destroyed blueprint
When you run `blueprints destroy`, it's as if you never used `blueprints init` during setup. The only difference is you still have all the files in your directory. To use this blueprint again and redeploy it, you'll need to let Sanity know about it. You can do this by running init again:
**npm**
```shell
npx sanity blueprints init
```
**pnpm**
```shell
pnpm dlx sanity blueprints init
```
**yarn**
```shell
yarn dlx sanity blueprints init
```
**bun**
```shell
bunx sanity blueprints init
```
This launches an editing interface that lets you reconfigure the blueprint, if needed, and it reconnects the blueprint to Sanity. Now you can add more functions or redeploy. Keep in mind that any environment variables added before destroying the blueprint will not carry over.
## Next steps
Now that you’ve defined your first PubSub function, [learn how to invoke it from other functions](https://www.sanity.io/docs/functions/function-to-function-invocation).
# Manage dependencies
Once you go beyond the basics of creating your first Function, you'll likely need to add dependencies ([like the @sanity/client](https://www.sanity.io/docs/functions/functions-js-client)). Functions use a dependency management system that tries to match how you'd like to work, while still remaining efficient.
This article explains the different approaches to using dependency packages in your functions. For guidance on file structures for the Blueprints configuration that Functions rely on in different project layouts and monorepo contexts, see [Project layout and monorepos](https://www.sanity.io/docs/blueprints/project-layout-and-monorepos).
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable writing and deploying a Sanity Function.
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
## Dependency placement
You have a few options for where to place a dependency, or package, as part of your function code.
### Project-level
Project-level dependencies are positioned alongside the `sanity.blueprint.ts` file and often defined at the root of the project. If you've initialized the blueprint with a TypeScript/JavaScript configuration, you already have a `package.json` at this level.
**Example structure**
```text
marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│ ├─ my-function/
│ │ ├─ index.ts
├─ sanity.blueprint.ts
├─ package.json <-- Install dependencies here, alongside the blueprint configuration file
├─ node_modules/
```
This allows you to manage your function dependencies alongside any project-wide dependencies, like developer dependencies, and share them across functions.
### Function-level
Sometimes it makes sense to keep a function and all of its dependencies contained in a single directory, separate from the concerns of the greater project.
To do this, navigate to the individual function's directory and initialize a new `package.json` with `npm init` or similar, and then add dependencies directly to the function.
**Example structure**
```text
marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│ ├─ my-function/
│ │ ├─ index.ts
│ │ ├─ package.json <-- Install dependencies here, alongside the function code
│ │ ├─ node_modules/
├─ sanity.blueprint.ts
```
### Mixed dependency environment
You may have instances where some functions use the function-level system, and others use the project-level system.
In this scenario, those using the function-level structure will use their own, co-located dependencies. Other functions will use the project-level dependency system.
Functions **will not** use or mix both sources. If you'd like a function using the function-level system to use a dependency from the project-level, you must also install it as a dependency at the function level.
**Example structure**
```text
marketing_site/
├─ studio/
├─ next-app/
├─ functions/
│ ├─ my-function/
│ │ ├─ index.ts
│ │ ├─ package.json <-- This is used for my-function
│ │ ├─ node_modules/
│ ├─ log-event/
│ │ ├─ index.ts
├─ sanity.blueprint.ts
├─ package.json <-- This is used for log-event
├─ node_modules/
```
## Moving between systems
If you have an existing function that's set up with the function-level system, you can migrate it to project-level in the following steps:
1. Add the function dependencies to the project-level package manifest. Either by using `npm install ` or by adding the packages to the file manually and running `npm install`.
2. Remove the `package.json` file and `node_modules` directory from the function folder.
The process is similar going in the other direction. To move from the project-level system to function-level for an individual function:
1. Navigate to the function's directory and initialize a `package.json` with `npm init` or similar.
2. Install any packages at this level, alongside your function code with `npm i `.
3. If the dependency is no longer required by other functions, remove the packages from the project-level `package.json` manually or by running `npm uninstall ` in the same directory as your `sanity.blueprint.ts` file.
# Local testing
Developing functions require a different mindset than developing your studio or front-end. They react to changes in your data. To avoid making a change, deploying, changing a document, and checking the logs of a function, you can take advantage of the included local testing tools to simulate how your functions will interact with your data.
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable writing and deploying a Sanity Function.
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
- Run the commands in this guide from the directory containing your blueprints configuration. If you're not already logged in, the CLI will prompt you to do so.
> [!NOTE]
> Keep in mind that testing locally will still verify that any supplied data matches your projections, filters, and any other criteria you've set in your function.
There are two approaches to running Sanity Functions locally. The `dev` command launches the development playground—a visual interface where you can run functions, edit the test data, and view the output. The `test` command offers a more traditional CLI experience where you can pass settings and test data directly as you invoke functions.
## Development playground
The Functions CLI includes an interactive playground where you can test your functions and see results prior to deploying them to Sanity's infrastructure.
Run the following command from your blueprint directory:
**NPM**
```sh
npx sanity@latest functions dev
```
**PNPM**
```sh
pnpx sanity@latest functions dev
```
This starts a local server running at `http://localhost:8080`. You can also specify a port with the `--port` flag.
### Parts of the playground interface
1. Select which project, dataset, event type, and API version you want to use to test the function.
2. Select the function you wish to test.
3. Toggle **"With Token"** to supply a `token` to the function handler's `context.clientOptions` object. A token is omitted from local testing unless this is toggled.
4. Optionally, pass a valid document ID and select the **download icon** to fetch the document and populate the sample document field with real data.
5. You can edit the document field manually, or use the download document option (4). The input expects a document-like shape. The "After document" field is only available when an *update* or *publish* event is selected.
6. Output from the function is displayed in the console. You can toggle the **"Preserve log"** option to keep logs between runs.
7. Run the function locally with the **"Run"** button.
You can stop the playground at any time by returning to your terminal and pressing `Ctrl+C`.
## The CLI `test` command
If you prefer a CLI-based testing interface, you can run the following command:
**PNPM**
```sh
pnpx sanity@latest functions test functionName
```
**NPM**
```sh
npx sanity@latest functions test functionName
```
Output from your functions will log to the console.
### Common CLI flags
The CLI includes flags to help you supply data and configuration settings to your functions. The following are some common flags in use. To see a full list, see the [functions CLI reference documentation](https://www.sanity.io/docs/cli-reference/functions) or run `npx sanity functions test --help`.
#### Supply data from a document in your dataset
Use the `--dataset`, `--project-id`, and `--document-id` flags to fetch real documents to use as source data for your function.
```sh
pnpx sanity@latest functions test log-event --document-id 52df8926-1afe-413b-bd23-e9efbc32cea3 --project-id 123456 --dataset production
```
#### Simulate event triggers
Sometimes you have logic in your function that reacts to different events, like `delta::operation`. Use the `--event` flag to simulate different event types. The default is `create`.
```sh
pnpx sanity@latest functions test log-event --event delete
```
#### Supply data from a file or string
**JSON file**
```sh
pnpx sanity functions test log-event --file sample-document.json
```
**Data string**
```sh
pnpx sanity functions test log-event --data '{ "_type": "post", "_id": "123456", "content": "test content" }'
```
#### Before/After data for delta GROQ
When paired with `--event update`, you can use `-before` and `-after` on the `--document-id`, `--data`, and `--file` flags to supply changes between two documents for delta GROQ functions.
```sh
pnpx sanity@latest functions test log-event --event update --document-id-before 52df8926-1afe-413b-bd23-e9efbc32cea3 --document-id-after 52354-1ad-654d-4565 --dataset production
```
#### Include your personal token for API calls
Local invocations don't include a `token` by default. By setting the flag, the function handler will have access to it at `context.clientOptions.token`.
```sh
pnpx sanity@latest functions test log-event --with-user-token
```
## Tips and best practices
### Use real data that matches your event
Your blueprint defines a function's event, including the filter and projection. The testing tools respect these settings and won't invoke a function if the incoming document shape wouldn't trigger it in a production setting.
### Detect local invocation
Even when you test your functions locally, your code still executes. If you're interacting with a Sanity dataset or external API from within a function, be careful not to trigger writes accidentally.
You can avoid accidental writes by checking if a function is invoked locally. Both the `test` and `dev` command set the `context.local` value to `true`. It remains undefined in deployed functions.
```
if (context.local) {
console.log('This code only runs when testing locally.')
}
if (!context.local) {
console.log('This code only runs in the deployed function.')
}
```
You can also pair this with the `dryRun` functionality in many Sanity libraries and APIs. For example:
**Patch**
```
// will set dryRun to true in test / dev
client
.patch('bike-123')
.set({inStock: false})
.inc({numSold: 1})
.commit({ dryRun: context.local })
```
**Actions**
```
// will set dryRun to true in test
client.action({
actionType: 'sanity.action.document.create',
publishedId: 'bike-123',
attributes: {name: 'Sanity Tandem Extraordinaire', _type: 'bike', seats: 1},
ifExists: 'fail',
},
{dryRun: context.local}
)
```
**Agent Actions**
```
client.agent.action.generate({
schemaId: 'your-schema-id',
documentId: 'your-document-id',
instruction: 'Write a summary for the following topic: $topic',
instructionParams: {
topic: 'Grapefruit',
},
target: {path: ['body']},
noWrite: context.local
})
```
# Function to function invocation
Sanity Functions can now invoke other Sanity Functions directly from within your code. Combined with Runtime resource discovery, this lets you chain, fan out, and compose function logic without routing everything back through document change events.
Previously, if one function's work needed to trigger another function, the only way was through document change events: a function would modify a document, that mutation would raise a new change event, and Sanity would invoke the next function in response. This worked, but it meant every step in a chain had to be modeled as a document mutation, even when no document change was actually the point.
Sanity Functions now support invoking a function directly from your code, and exposes the other resources in your Blueprint (functions, CORS origins, datasets, etc.) so you can reference them by name at runtime.
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable creating and deploying a function.
- Use the latest version of the `sanity` CLI (`sanity@latest`) to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
## Chaining function invocations
**Without invoke:** chaining through document events
1. Modifying a document raises a document change event.
2. Sanity invokes your code.
3. Your code modifies the document.
4. Another document change event is raised.
5. Sanity invokes the next function.
6. Repeat for each step in the chain.
Every link in the chain depended on a document mutation to trigger the next one, even for steps that had nothing to do with the document itself, such as posting a Slack message or calling an external API.
**With invoke:** chaining through invoke
1. Modifying a document raises a document change event.
2. Sanity invokes your code.
3. Your code invokes a [Sanity PubSub Function](https://www.sanity.io/docs/functions/pubsub-function-quickstart) directly.
The intermediate document mutation is no longer required. A function can call the next step in the pipeline as a normal function call.
## Why use invoke?
**Function composition.** Break logic into small, focused functions and call them from one another, instead of duplicating logic across functions.
**Fan-out processing.** A single function can invoke many others in parallel, distributing heavy workloads across multiple invocations rather than processing everything serially in one function.
**Privilege separation.** A broadly-permissioned function can hand off sensitive operations to a narrowly-scoped function, rather than holding every permission itself.
**Resource isolation.** Different workloads can run with their own memory and timeout configurations, invoked dynamically from a coordinating function instead of being forced to share one configuration.
## How to invoke a function
### Step 1: Create a PubSub function
Create a pubsub function, a Sanity Function you can trigger from other functions.
**functions/slack-post/index.ts**
```typescript
import { pubSubEventHandler } from '@sanity/functions'
export const handler = pubSubEventHandler(
async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`Your pubsub Sanity Function was called at ${time}`)
}
)
```
### Step 2: Add it to your Blueprint
Add this new function to your Blueprint.
**sanity.blueprint.ts**
```
import { defineBlueprint, definePubSubFunction }
from '@sanity/blueprints'
export default defineBlueprint({
resources: [
definePubSubFunction({ name: 'slack-post' })
],
})
```
### Step 3: Import `invoke`
Import `invoke` from the standard functions library in any function that you want to `invoke` other functions.
**functions/calling-slack-post/index.ts**
```typescript
import { invoke } from '@sanity/functions'
```
### Step 4: Call `invoke`
Call `invoke` with the name of the target function, passing along your `context` and the event payload you want it to receive.
**functions/calliing-slack-post/index.ts**
```typescript
await invoke('slack-post', {
context,
event: { data: message }
})
```
The target function (`slack-post` in this example) runs as its own function invocation, receiving whatever `context` and `event` you pass it - it doesn't need to know it was invoked by another function rather than by a document event.
## Understanding invoke's execution modes
`invoke` takes an optional third parameter, `{ sync: boolean }`. If you omit it, `sync` defaults to `false`. This is the existing async behavior, unchanged. If you pass `{ sync: true }`, `invoke` waits for the target function to finish and gives you back its response.
### Async (default): fire-and-forget
`invoke` resolves as soon as the target function's invocation request is *accepted.* It does not wait for that function to finish running. If the request itself is rejected (bad name, bad payload, etc.), `invoke` throws. A resolved async `invoke` call tells you "the function was triggered," not "the function is done."
#### ❌ Wrong: assuming async invoke waits for a result
**index.ts**
```typescript
import { invoke } from '@sanity/functions'
export default async function handler(context, event) {
// WRONG - async invoke does not return the invoked function's
// output.
// This will be undefined even though 'slack-post' ran successfully.
const result = await invoke('slack-post', {
context,
event: { data: event.data }
})
if (result.ok) {
// Never behaves as expected - `result` isn't the invoked
// function's return value in async mode.
console.log('Message posted:', result.ok)
}
}
```
Or…
**index.ts**
```typescript
// WRONG - chaining logic that depends on the invoked function
// having already completed its work.
await invoke('resize-image', { context, event })
// Runs immediately after invoke() resolves, not after
// resize-image actually finishes resizing anything.
const resized = await client.fetch
(`*[_id == $id][0].resizedUrl`, { id: event.data._id })
```
#### ✅ Correct: treat async invoke as fire-and-forget
**index.ts**
```typescript
import { invoke } from '@sanity/functions'
export default async function handler(context, event) {
try {
// sync defaults to false - invoke resolves once the call
// is accepted, that's all we can rely on here.
await invoke('slack-post', {
context,
event: { data: event.data }
})
} catch (err) {
// Only errors *accepting* the invocation land here
// (bad function name, malformed payload, etc.)
console.error('Failed to trigger slack-post:', err)
}
}
```
Or…
**index.ts**
```typescript
// ✅ Correct: fan-out, where each invoked function is
// independent and doesn't need to report back synchronously.
await Promise.all(
batches.map((batch) =>
invoke('process-batch', { context, event: { data: batch } })
)
)
// All we know here: every batch was accepted for processing,
// not that processing is complete.
```
### Sync: waiting for a response
Passing `{ sync: true }` as the third argument tells `invoke` to wait for the target function to finish executing, and to return its response.
**index.ts**
```typescript
const response = await invoke(
'slack-post',
{ context, event: { data: event.data } },
{ sync: true }
)
```
Use this only when your function's next step genuinely depends on the invoked function's output or on it having definitely finished. For example, a validation function that needs a yes/no answer before deciding whether to proceed. Sync invocation should be the exception, not the default. It ties up your caller's execution (and its timeout/memory budget) for as long as the callee takes to run, and it forces steps to execute one at a time instead of in parallel. This is the opposite of what fan-out and privilege separation are meant to achieve. If you find yourself reaching for `{ sync: true }` in most of your `invoke` calls, that's usually a sign the logic belongs in one function rather than two.
#### ❌ Wrong: sync invocation as the default habit
**index.ts**
```typescript
// WRONG - no actual dependency on the result; this should
// just be a normal async invoke.
const response = await invoke(
'slack-post',
{ context, event: { data: event.data } },
{ sync: true }
)
// response is never used - we paid for a synchronous wait
// for nothing.
```
Or…
**index.ts**
```typescript
// WRONG - using sync to fan out, defeating the purpose of
// parallel, independent invocations.
for (const batch of batches) {
await invoke('process-batch', {
context,
event: { data: batch }
},
{ sync: true }
)
}
// This serializes what should be parallel work, and blocks
// this function until every batch finishes one at a time.
```
#### ✅ Correct: sync invocation for a genuine dependency
**index.ts**
```typescript
export default async function handler(context, event) {
// We can't proceed without knowing whether this content
// passes validation - that can only be answered synchronously.
const response = await invoke(
'validate-content',
{ context, event: { data: event.data } },
{ sync: true }
)
if (!response.valid) {
return { skipped: true, reason: response.reason }
}
// Only now, with a real answer in hand, do we continue.
await invoke('publish-content', {
context,
event: { data: event.data } }
)
}
```
## Deciding which mode to use
##### Choosing between Async and Synchronous invocation
| | **Async (default / sync: false)** | **Sync (sync: true)** |
| --- | --- | --- |
| Waits for completion? | No - only for acceptance | Yes |
| Returns callee's response? | No | Yes |
| Best for | Fan-out, chaining steps, privilege separation | Steps that genuinely can't proceed without the callee's result |
| Use liberally? | Yes, this is the default pattern | No - reserve for cases async can't solve |
## Example: fan out
In this example our function receives a document mutation event when a blog post goes from draft to published. The act of publishing means we want to blast out this new blog post to all of our socials.
At a high level, the pipeline looks like:
1. Our document change function is invoked when the post becomes published.
2. The function invokes many functions in parallel to post to social media sites.
**index.ts**
```typescript
import { documentEventHandler, invoke } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 A new blog post has been published at ${time}`)
await Promise.all([
invoke('post-to-bluesky', { context, event }),
invoke('post-to-linkedin', { context, event }),
invoke('post-to-mastodon', { context, event }),
invoke('post-to-threads', { context, event }),
invoke('post-to-x', { context, event }),
])
})
```
This mirrors the fan-out pattern above: the document change logic and the social-posting logic stay in separate, independently-configured functions, connected by `invoke` instead of a document mutation.
# Configure @sanity/client
Functions have the ability to connect back to Sanity and manipulate not only the incoming document, but any document in your dataset. By including details about your project in the context, Functions enable you to configure a `@sanity/client` instance and interact with any Sanity API.
In this guide, you'll learn to install and configure `@sanity/client` in a Sanity Function. Then you'll use it to make interact with your project dataset.
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable writing and deploying a Sanity Function. This guide assumes you have a blueprint defined with a function you want to add the client to.
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
## Add `@sanity/client` to your function
To install the Sanity client, add it to your project at the blueprints root (where your `sanity.blueprint.ts` file is).
**NPM**
```sh
npm install @sanity/client
```
**PNPM**
```sh
pnpm add @sanity/client
```
> [!TIP]
> Function dependencies
> Functions can be self-contained, managing their own dependencies, or share dependencies with other functions in the Blueprint. This guide adds dependencies at the Blueprint level, where all functions can import them.
> If you prefer, you can keep each function self-contained by adding dependencies directly to individual function folders. To do so, navigate to the function folder before installing the package. In this case, the function will only use it's local dependencies.
> Learn more in the guide on [managing function dependencies](https://www.sanity.io/docs/functions/function-dependencies).
Once the install completes, open the function's `index.ts` file and update the starter code.
- Import `createClient` .
- Use `context.clientOptions` to configure the client.
- Make and log a request to the API to test the client.
**index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = documentEventHandler(async ({ context, event }) => {
const client = createClient({
...context.clientOptions,
apiVersion: '2025-05-08',
})
const posts = await client.fetch('*[_type == "post"]')
console.log(posts)
})
```
**index.js (JavaScript**
```javascript
import { createClient } from '@sanity/client'
export async function handler({context, event}) {
const client = createClient({
...context.clientOptions,
apiVersion: '2025-05-08',
})
const posts = await client.fetch('*[_type == "post"]')
console.log(posts)
}
```
The context includes a `clientOptions` object with details about your project, dataset, and a robot token. Use `clientOptions` along with any preferred settings to create a new client. Aside from the values included with `clientOptions`, you must also set your preferred `apiVersion`. You should also set the `useCdn` option, along with any other client configuration settings you need for your specific request.
When developing locally with the `test` command, `clientOptions` only contains the `projectId` and `apiHost` values. You can pass additional values to `clientOptions` by using flags when running the test. The `--dataset` command lets you define the dataset, and `--with-user-token` will pass your user token. For example:
```sh
pnpx sanity functions test event-log --dataset production --with-user-token
```
> [!TIP]
> Obfuscated tokens
> Logs will obfuscate `clientOptions.token` by replacing parts of the token with asterisks. This is limited to logging, and you can safely use the token to make API calls.
You can read more about clientOptions and all available properties in the [handler reference](https://www.sanity.io/docs/functions/function-wrapper).
Additional client-specific configuration options, and usage guides for the JavaScript client are available in the [@sanity/client getting started guide](https://www.sanity.io/docs/apis-and-sdks/js-client-getting-started).
## Preventing writes during testing
The `sanity functions test` and `dev` commands simulate a function invocation, but they still execute your code. This can lead to mutations. To prevent this, you can take advantage of `context.local`.
You can wrap mutations in a conditional check to limit their execution to production only.
```
// Check if function context is NOT test/dev
if (!context.local) {
await client.createOrReplace(doc)
}
```
You can also use `context.local` with the `dryRun` or `noWrite` options for various mutations and actions.
**Patch**
```
// will set dryRun to true in test / dev
client
.patch('bike-123')
.set({inStock: false})
.inc({numSold: 1})
.commit({ dryRun: context.local })
```
**Actions**
```
// will set dryRun to true in test
client.action({
actionType: 'sanity.action.document.create',
publishedId: 'bike-123',
attributes: {name: 'Sanity Tandem Extraordinaire', _type: 'bike', seats: 1},
ifExists: 'fail',
},
{dryRun: context.local}
)
```
**Agent Actions**
```
client.agent.action.generate({
schemaId: 'your-schema-id',
documentId: 'your-document-id',
instruction: 'Write a summary for the following topic: $topic',
instructionParams: {
topic: 'Grapefruit',
},
target: {path: ['body']},
noWrite: context.local
})
```
## Use the client with Media Library
Accessing Media Library (ML) with the client from functions require some additional information.
> [!NOTE]
> ML support in functions requires `@sanity/blueprints` v0.4.0 or later and `@sanity/functions` v1.1.0 or later. ML support in `@sanity/client` requires v7.14.1 or later.
### Media Library Functions
If your function is a Media Library function, one triggered by events in the Media Library, you can get the Media Library identifier from the `context`.
The `context.eventResourceId` will be your Media Library's identifier. Keep in mind that in non-media-library functions, this identifier will be that of the triggering resource, like a dataset.
**index.ts**
```
import { documentEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = documentEventHandler(async ({ context, event }) => {
// This will be the Media Library ID of the triggering library
const { eventResourceId } = context
// Configure the client to make requests to Media Library
const client = createClient({
...context.clientOptions,
apiVersion: '2025-05-08',
resource: {
type: 'media-library',
id: eventResourceId
}
})
const QUERY = `*[_type == 'sanity.imageAsset']`
const response = await client.fetch(QUERY)
})
```
### Document Functions
If your function is a document function, one not triggered by a Media Library event, you'll need to pass the ML identifier in another way. Either by hard-coding it in the function, or by setting it as an [environment variable](https://www.sanity.io/docs/functions/function-env-vars).
## Use the client in a scheduled function
If you plan to interact with a Sanity project’s dataset from your scheduled function, you can [install the Sanity client](https://www.sanity.io/docs/functions/functions-js-client) and configure it. As scheduled functions are organization-scoped, they don’t have a project and dataset in their `context`. You need to explicitly [define a robot token](https://www.sanity.io/docs/functions/robot-tokens-with-functions) and set the projectId and dataset when configuring the client.
Create the robot token in your blueprint and reference it from the scheduled function definer:
**sanity.blueprint.ts**
```
import { defineBlueprint, defineScheduledFunction, defineRobotToken } from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'my-robot',
label: 'My Robot',
memberships: [
{
resourceType: 'project',
resourceId: 'abc123',
roleNames: ['editor'],
},
],
}),
defineScheduledFunction({
name: 'expire-cache',
event: {expression: '0 0 * * *'},
robotToken: '$.resources.my-robot.token',
}),
],
})
```
Configure the client:
**index.ts**
```
import { scheduledEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = scheduledEventHandler(async ({ context }) => {
const time = new Date().toLocaleTimeString()
console.log(`👋 Your Sanity Function was called at ${time}`)
const client = createClient({
projectId: 'YOUR_PROJECT_ID',
dataset: 'YOUR_DATASET',
apiVersion: '2026-04-29',
token: context.clientOptions?.token,
})
})
```
## Tips for using the client
- The `sanity functions test` command won't include a token or dataset by default. To include a token in `context.clientOptions`, run the command with the `--with-user-token` flag. To set a dataset, use the `--dataset my-dataset-name` flag, replacing the value with your project's dataset.
- Be cautious mutating the incoming document—the one that triggered the function—in a way that will trigger it again. The client limits recursive chains to 16 invocations.
- Don't re-fetch the `event` document unless you need. Use the incoming payload to save a request.
- The Sanity client isn't required to make requests to Sanity. If you're focused on the fastest, lightest function possible, you can build API calls manually with Node's `fetch` and the token, projectId, and dataset from `context.clientOptions`.
# Add environment variables
Environment variables let you keep secrets, like tokens or API keys, hidden and out of version control. Sanity Functions lets you manage environment variables from the CLI so they're available to your deployed functions.
In this guide, you'll learn to add environment variables and access them from within your function code.
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable creating and deploying a function.
- Use the latest version of the `sanity` CLI (`sanity@latest`) to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
## Create a function
If you don't already have a blueprint and function set up, create them now.
Initialize a blueprint:
**npm**
```shell
npx sanity@latest blueprints init
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints init
```
**yarn**
```shell
yarn dlx sanity@latest blueprints init
```
**bun**
```shell
bunx sanity@latest blueprints init
```
Add a function:
**npm**
```shell
npx sanity@latest functions add
```
**pnpm**
```shell
pnpm dlx sanity@latest functions add
```
**yarn**
```shell
yarn dlx sanity@latest functions add
```
**bun**
```shell
bunx sanity@latest functions add
```
In this example, set the function to trigger on **Document Create** and **Document Update**, use **TypeScript**, and set the name to `envExample`.
**Output**
```text
✔ Enter function name: envExample
✔ Choose events to trigger your function: Document Create, Document Update
✔ Choose function language: TypeScript
✔ Add @sanity/functions helpers to the new Function? yes
✔ How to install the @sanity/functions helpers: npm
```
This creates a function in the `functions/envExample` directory.
## Develop locally
Variables added with `functions env add` aren't available locally, but you can simulate them by prefixing your CLI command with the variable and value.
Start by updating the function to display the variable. This example uses a variable called `SANITY_SECRET_SAUCE`.
**index.ts (TypeScript)**
```typescript
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
})
```
**index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
console.log(`The secret: ${process.env.SANITY_SECRET_SAUCE}`)
}
```
All environment variables are accessible on `process.env`.
To test the function's access to a variable, prefix the CLI command with it.
**CLI**
```sh
SANITY_SECRET_SAUCE="content operating system" npx sanity@latest functions test envExample
```
If everything worked, you'll see this output:
**Output**
```text
Logs:
The secret: content operating system
```
Now that it works locally, make the same variable available to your deployed function.
## Add an environment variable
Before you can add environment variables, you need to deploy the blueprint.
**npm**
```shell
npx sanity@latest blueprints deploy
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints deploy
```
**yarn**
```shell
yarn dlx sanity@latest blueprints deploy
```
**bun**
```shell
bunx sanity@latest blueprints deploy
```
With the blueprint deployed, you can add environment variables to the function.
Add them with the `sanity functions env add FUNCTION_NAME VARIABLE_NAME VARIABLE_VALUE` command.
**npm**
```shell
npx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"
```
**pnpm**
```shell
pnpm dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"
```
**yarn**
```shell
yarn dlx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"
```
**bun**
```shell
bunx sanity@latest functions env add envExample SANITY_SECRET_SAUCE "content operating system"
```
Create or update a document to trigger the function, then check the function's logs. The output matches the one from the local test.
**npm**
```shell
npx sanity@latest functions logs envExample
```
**pnpm**
```shell
pnpm dlx sanity@latest functions logs envExample
```
**yarn**
```shell
yarn dlx sanity@latest functions logs envExample
```
**bun**
```shell
bunx sanity@latest functions logs envExample
```
You've now deployed and accessed an environment variable from a function.
When you're done with this function and blueprint, `destroy` the blueprint to prevent unexpected billing:
**npm**
```shell
npx sanity@latest blueprints destroy
```
**pnpm**
```shell
pnpm dlx sanity@latest blueprints destroy
```
**yarn**
```shell
yarn dlx sanity@latest blueprints destroy
```
**bun**
```shell
bunx sanity@latest blueprints destroy
```
## List and remove environment variables
Environment variables are linked to individual functions. In addition to `add`, you can use the following commands to interact with them:
- `sanity functions env list FUNCTION_NAME`: List the environment variable keys set on the given function. Values are never displayed.
- `sanity functions env remove FUNCTION_NAME VARIABLE_NAME`: Remove the variable from the deployed function.
For additional usage information, add `--help` after each CLI command. You can read more about the CLI in the [Functions CLI reference](https://www.sanity.io/docs/cli-reference/functions).
## Troubleshooting
### Adding a variable before deploying
`sanity functions env add` writes to the Sanity’s Functions service, not to your local blueprint. The function has to exist in a deployed stack first, so running it before `sanity blueprints deploy` fails. The command doesn't warn and continue; it stops. `env list` and `env remove` behave the same way.
Which message you get depends on how far the CLI gets:
- `Missing Stack: provide --stack, or set a Stack in your Blueprint config (`sanity blueprints config --edit`).`: No stack is configured yet.
- `Missing Stack deployment`: A stack ID is set, but no deployment exists to load.
- `Unable to find deployed function: "FUNCTION_NAME"`: The stack is deployed, and the function is declared locally but isn't in the deployment yet.
- `Unable to find function: "FUNCTION_NAME"`: The name doesn't match any function in the stack.
None of these messages tells you to deploy. They point you at `sanity blueprints doctor`, which reports the configuration problem but not the ordering mistake behind it. Run `sanity blueprints deploy` first, then add the variable. Adding a variable doesn't redeploy the stack, and the new value takes effect on the next function invocation.
### Running the command outside a blueprint directory
Run the command from the blueprint directory or a subdirectory. The manifest is required even though the command only touches remote state. Without it you get `Could not find a Blueprint manifest (sanity.blueprint.ts, .js, or .json).` If the API rejects the change after the function resolves, the CLI reports `Failed to update VARIABLE_NAME` with the reason from the Functions API.
# Assign custom robot tokens
Robot tokens enable your functions to authenticate API calls to Sanity without managing credentials manually. You can choose to create a token yourself as shown in this guide, or one will be created when you deploy your blueprint.
Prerequisites:
- Functions run on Node.js v24.x.
- The latest version of the Sanity CLI is recommended. Run commands with `npx sanity@latest`.
- A Sanity project ID where you have permission to create robots and deploy functions.
## Robot tokens
Robots are service accounts that provide authentication tokens for automated access. When you define a token in a blueprint:
1. The token is created during deployment with the specified roles.
2. A token is generated and managed by Sanity.
3. Functions reference the token like so: `$.resources..token`.
4. The token is injected into your function to be used at function runtime.
These are similar to [robot tokens defined in your project or organization settings](https://www.sanity.io/docs/content-lake/http-auth), but they are [managed by the blueprint](https://www.sanity.io/docs/blueprints/blueprints-robot-tokens) instead.
## Define a robot token
Use the `defineRobotToken` helper to define a token in your blueprint configuration.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineRobotToken} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'my-robot',
label: 'My Robot',
memberships: [
{
resourceType: 'project',
resourceId: 'abc123',
roleNames: ['editor'],
},
],
})
]
})
```
You can find a list of available roles for your project with the [Access API](https://www.sanity.io/docs/http-reference/access-api#getroles), or by viewing the roles in manage.
A complete list of configuration options is available in [the reference documentation](https://reference.sanity.io/_sanity/blueprints/defineRobotToken/).
### Using the token in Functions
Reference the robot token in your Function definition:
**sanity.blueprint.ts**
```
import {defineBlueprint, defineRobotToken, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRobotToken({
name: 'my-robot',
label: 'My Robot',
memberships: [
{
resourceType: 'project',
resourceId: 'abc123',
roleNames: ['editor'],
},
],
}),
defineDocumentFunction({
name: 'my-function',
robotToken: '$.resources.my-robot.token',
// ... rest of config
}),
]
})
```
When configured like this, your function receives the token as part of the `context.clientOptions` and can be used to [configure a Sanity client](https://www.sanity.io/docs/functions/functions-js-client).
## Define custom roles
**This is a paid feature**
This feature is available on certain Enterprise plans. [Talk to sales](https://www.sanity.io/contact/sales?ref=docs) to learn more.
You can [define custom roles in the blueprint](https://www.sanity.io/docs/blueprints/blueprints-role), then use them to define a robot token. This example defines a role, `function-user`, then defines a robot with as a member of that role, and finally assigns that robot token to the function.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineRobotToken, defineRole, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineRole({
name: 'function-user',
title: 'Function User',
permissions: [
{
name: 'read-documents',
action: 'read',
filter: '_type == "post"',
},
{
name: 'write-documents',
action: 'update',
filter: '_type == "post"',
},
],
}),
defineRobotToken({
name: 'my-robot',
memberships: [
{
resourceType: 'project',
resourceId: 'abc123',
roleNames: ['function-user'],
},
],
}),
defineDocumentFunction({
name: 'my-function',
robotToken: '$.resources.my-robot.token',
// ... rest of config
}),
]
})
```
## Best practices
### Apply least privilege
Create custom roles with only the permissions your function needs, as shown in the role example above.
### Keep credentials out of source control
The actual token value is managed by Blueprints and never stored in your repository.
### Match Node.js versions
Use Node.js v24.x locally to match the Functions runtime and avoid unexpected behavior.
## Troubleshooting
### Validation error: "robotToken must be a string"
Ensure the value is exactly `$.resources..token` (a string, not an object or function call).
### Permission denied at runtime
The robot's roles don't permit the operation. Review `memberships.roleNames` and ensure the assigned roles grant the necessary permissions.
# Common patterns
Functions create the ability for countless content-driven opportunities. This guide collects common patterns and approaches to working with Functions.
Prerequisites:
- Complete the [Functions quick start](https://www.sanity.io/docs/functions/function-quickstart), or be comfortable writing and deploying a Sanity Function.
- The latest version of `sanity` CLI (`sanity@latest`) is recommended to interact with Blueprints and Functions as shown in this guide. You can always run the latest CLI commands with `npx sanity@latest`.
The examples below assume you've created a new function, and configured it to trigger based on your own schema requirements.
## Explore the exchange
Looking for more ideas and ready-made functions? Check out the a curated list in the exchange.
#### Explore more functions
[Auto-tag blog posts](https://www.sanity.io/recipes/auto-tag-function-ba7ce6e2)
AI-powered automatic tagging for Sanity blog posts that analyzes content to generate 3 relevant tags, maintaining consistency by reusing existing tags from your content library.
[Algolia Sync](https://www.sanity.io/recipes/algolia-sync-function-cae9ec0f)
Automatically update your Algolia index
[Post to Bluesky](https://www.sanity.io/recipes/post-to-bluesky-fd18322f)
Notify your audience when you publish a new document.
[Explore more recipes](https://www.sanity.io/recipes)
See more official and community functions on the Exchange.
## Ping an endpoint on publish
A common approach to invalidating CDNs and triggering new builds is to ping, or make a GET request, to an endpoint. Some require you to provide specifics, such as the endpoint or slug for targeted refreshes. Others only require a single URL.
Create a function and configure it to trigger when your target document publishes. For the example, make sure to [define an environment variable](https://www.sanity.io/docs/functions/function-env-vars) named `DEPLOY_HOOK_URL`.
**index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
const URL = process.env.DEPLOY_HOOK_URL
if (!URL) {
throw new Error("DEPLOY_HOOK_URL is not set")
}
try {
await fetch(URL)
} catch (error) {
console.error(error)
}
})
```
**index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
const URL = process.env.DEPLOY_HOOK_URL
if (!URL) {
throw new Error("DEPLOY_HOOK_URL is not set")
}
try {
await fetch(URL)
} catch (error) {
console.error(error)
}
}
```
To find the deploy or trigger URL for your provider, check their documentation. We've included a few common links below:
- [Vercel: Create and trigger deploy hooks](https://vercel.com/docs/deploy-hooks)
- [Azure: purge content](https://learn.microsoft.com/en-us/rest/api/cdn/endpoints/purge-content?view=rest-cdn-2025-04-15&tabs=HTTP)
- [Cloudflare: purge cache](https://developers.cloudflare.com/api/resources/cache/methods/purge/)
## Automatically translate documents
You can combine Agent Actions Translate with Functions to translate documents automatically.
We recommend completing [the quick start](https://www.sanity.io/docs/agent-actions/translate-quickstart) if you haven't used Translate before.
First, create a function and configure it to only trigger when a document's language is in your "from" language. Here's an example of the function resource in `sanity.blueprint.ts`.
**sanity.blueprint.ts**
```typescript
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: "translate",
event: {
on: ["publish"],
filter: "_type == 'post' && language == 'en-US'",
projection: "{_id}"
}
}),
],
})
```
> [!TIP]
> Use caution when creating documents
> The GROQ filter in this example is important. It makes sure that the function only runs when the language is set to English. When we generate a new translation in the next code block, Translate sets that field to Greek. This stops the new document from triggering the same function and creating a recursive loop.
> You could also create draft or version documents to prevent the "on publish" function from triggering.
For this approach, we have documents with a `language` set. We only want the English language files.
1. [Import and configure the @sanity/client](https://www.sanity.io/docs/functions/functions-js-client).
2. Capture the document `data` from the `event`.
3. Construct a `translate` request.
**index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = documentEventHandler(async ({ context, event }) => {
const { data } = event
const client = createClient({
...context.clientOptions,
apiVersion: 'vX',
})
const targetLanguage = {
id: "el-GR",
title: "Greek"
}
// Create a consistent ID based on the source and target language.
// This allows the function to override the document in the future
const targetId = `${data._id}-${targetLanguage.id}`
try {
await client.agent.action.translate({
// Replace with your schema ID
schemaId: "your-schema-id",
// Tell the client to run the action asynchronously.
// We don't need to wait for it to complete.
async: true,
// Tell the client the ID of the document to use as the source.
documentId: data._id,
// Set the language field to the target language.
languageFieldPath: "language",
// Set the operation mode
// createOrReplace will override the ID in future invocations.
targetDocument: {
operation: "createOrReplace",
_id: targetId
},
// Set the 'from' and 'to' language
fromLanguage: {id: "en-US", title: "English"},
toLanguage: {id: targetLanguage.id, title: targetLanguage.title},
});
} catch (error) {
console.error(error)
}
})
```
**index.js (JavaScript)**
```javascript
import { createClient } from '@sanity/client'
export async function handler({context, event}) {
const { data } = event
const client = createClient({
...context.clientOptions,
apiVersion: 'vX',
})
const targetLanguage = {
id: "el-GR",
title: "Greek"
}
// Create a consistent ID based on the source and target language.
// This allows the function to override the document in the future
const targetId = `${data._id}-${targetLanguage.id}`
try {
await client.agent.action.translate({
// Replace with your schema ID
schemaId: "your-schema-id",
// Tell the client to run the action asynchronously.
// We don't need to wait for it to complete.
async: true,
// Tell the client the ID of the document to use as the source.
documentId: data._id,
// Set the language field to the target language.
languageFieldPath: "language",
// Set the operation mode
// createOrReplace will override the ID in future invocations.
targetDocument: {
operation: "createOrReplace",
_id: targetId
},
// Set the 'from' and 'to' language
fromLanguage: {id: "en-US", title: "English"},
toLanguage: {id: targetLanguage.id, title: targetLanguage.title},
});
} catch (error) {
console.error(error)
}
}
```
Now, when you publish an English-language document, it will create a Greek version. [Learn more about Agent Actions here](https://www.sanity.io/docs/agent-actions/introduction).
## Set an undefined value with `setIfMissing`
You may have values in documents that are sometimes set by people, but otherwise could be derived programatically. This example uses GROQ's `!defined` function and a `setIfMissing` patch to add a the current date and time as the published date to a document, but only when it hasn't been set.
For this example, you'll need to:
1. Set up a new function or edit an existing one.
2. Import and configure the `@sanity/client` if you haven't already.
First, modify the following filter and add it to your function's `event` in the `sanity.blueprint.ts` configuration.
```text
"filter": "_type == 'post' && !defined(firstPublished)"
```
Adjust the `_type` and `firstPublished` values to match properties from your schema. `!defined` checks that the property is not set, which prevents the function from running if the document receives future updates.
Next, create a `setIfMissing` patch to set the same field from the filter. `setIfMissing` is redundant here, as it *should* be empty if `!defined` worked as intended. It's still a useful to approach when you only want to update empty fields.
**index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'
export const handler = documentEventHandler(async ({ context, event }) => {
const { data } = event
const client = createClient({
...context.clientOptions,
apiVersion: "2026-02-27"
})
try {
await client.patch(data._id, {
setIfMissing: {
firstPublished: new Date().toISOString()
}
}).commit()
} catch (error) {
console.error(error)
}
})
```
**index.js (JavaScript)**
```javascript
import { createClient } from '@sanity/client'
export async function handler({context, event}) {
const { data } = event
const client = createClient({
...context.clientOptions,
apiVersion: "2026-02-27"
})
try {
await client.patch(data._id, {
setIfMissing: {
firstPublished: new Date().toISOString()
}
}).commit()
} catch (error) {
console.error(error)
}
}
```
## Scope Functions to a specific dataset
By default, your functions run against all datasets for the project they've been configured with. You can define a [resource](https://www.sanity.io/docs/blueprints/blueprint-config) in your functions config to cause only changes in a specific dataset to trigger functions.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: "log-event",
event: {
on: ["update"],
filter: "_type == 'post'",
resource: {
type: 'dataset',
id: 'myProjectId.production'
},
},
})
]
})
```
Alternatively, you can also narrow dataset scope with filters and the `sanity::dataset()` function.
**sanity.blueprint.ts**
```
import {defineBlueprint, defineDocumentFunction} from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineDocumentFunction({
name: "log-event",
event: {
on: ["update"],
filter: "_type == 'post' && sanity::dataset() == 'production'",
},
})
]
})
```
## Use Functions with Media Library assets
To configure a function to react to changes in assets in Media Library, use the `defineMediaLibraryAssetFunction` helper and configure the [resource object](https://www.sanity.io/docs/blueprints/blueprint-config).
You can try things like:
- Comparing changes in an asset's aspect data.
- Kicking off a review flow when new versions are added to an asset.
- Update references when assets are deleted.
> [!WARNING]
> If you're using the TS/JS configuration format, you'll need to update `@sanity/blueprints` to v0.4.0 or later to access `defineMediaLibaryAssetFunction`.
Asset functions only support the `sanity.asset` document `_type`. You can apply additional filters, but it will only run on documents of this type.
For example, this function will run whenever someone deletes an asset that's referenced by another document in your organization.
**sanity.blueprint.ts**
```
import { defineBlueprint, defineMediaLibraryAssetFunction } from '@sanity/blueprints'
export default defineBlueprint({
resources: [
defineMediaLibraryAssetFunction({
name: 'ml-asset',
event: {
on: ['delete'],
filter: "documents::incomingGlobalDocumentReferenceCount() > 0",
projection: "{_id, versions, title}",
resource: {
type: 'media-library',
id: 'mlFqEeKZYecz',
}
},
})
],
})
```
If you need to query or mutate ML documents from your function, make sure to [configure the @sanity/client](https://www.sanity.io/docs/functions/functions-js-client) for use with Media Library.
Learn more about working with Media Library documents in the [Media Library documentation](https://www.sanity.io/docs/media-library/introduction).
## Enable recursion control in unofficial clients
Sanity client (`@sanity/client` v7.12.0 or later) includes recursion protection by reading and setting a lineage header. If you're mutating documents from a function and not using the client, you can implement this functionality yourself.
1. Read the `process.env.X_SANITY_LINEAGE` environment variable.
2. Pass the value to the `X-Sanity-Lineage` header of any requests that mutate a document.
This allows Sanity's infrastructure to limit function invocation chains just as it does for the official client.
# Handler reference
[Overview](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.
[Quick start](https://www.sanity.io/docs/functions/function-quickstart)
Start building with Functions by deploying a new function to Sanity's infrastructure.
Every Function must export a `handler`. Handlers contain the logic that the Function infrastructure runs when your document changes trigger the function.
Create a function handler with the `sanity blueprints add function` command. Every handler receives an object containing `context` and `event` parameters. The function does not require a return value.
## `context` properties
#### Properties
**clientOptions** (object)
Provides properties for configuring the Sanity client (@sanity/client). Most commonly used to pass details about the invoking project dataset to a client configuration. See the configuring @sanity/client in Functions guide for details.
**local** (boolean)
The context.local value is set to true for functions invoked with sanity functions test and sanity functions dev. This can be helpful when you want code to only execute in local environments.
It is undefined for functions in production.
**eventResourceType** (string)
The resource type that triggered the function. For Document functions, this would be dataset. For Media Library functions, this would be media-library.
**eventResourceId** (string)
The resource ID that triggered the function. For Document functions, this would be the ID of a dataset in the form .. For Media Library functions, this would be the Media Library id.
### `clientOptions` properties
#### Properties
**projectId** (string)
The ID of the project that triggered this function.
**dataset** (string)
The dataset name of the project that triggered this function.
The sanity functions test command won't include a dataset by default. Run with the --dataset flag to pass a dataset to clientOptions. For example: sanity functions test log-event --dataset production
**apiHost** (string)
Defaults to https://api.sanity.io.
**token** (string)
A token with access to your Sanity project. It is recommended to define a Robot Token Blueprint resource yourself with permissions with explicit permissions and assign the token to your Function resource. For sanity.function.document Functions, this token is automatically generated with the editor role and added to your project when deploying the blueprint. For other function types, you must explicitly define a Robot Token resource. See Using robot tokens with Functions for more details.
The sanity functions test command won't include a token by default. Run with the --with-user-token flag to pass a the logged-in user's token.
Note: the token is obfuscated in logs for security. You can directly use it to configure the Sanity client or to make API calls.
### Example context
```javascript
{
clientOptions: {
apiHost: 'https://api.sanity.io',
projectId: 'abc123',
dataset: 'production',
token: '***************'
}
}
```
## `event` properties
Contains the shape of the event, which depends on the event:
- In the case of `document` and `media-library` Function events, like `publish`, the event shape is the document. This will vary based on your schema.
- In the case of `sync-tag-invalidate` Function events, the sync tags will be present under `event.data.syncTags`.
### Example `document` event
```javascript
{
data: {
_id: '1234',
_type: 'article',
title: 'Functions quick start',
_createdAt: '2025-04-24T16:26:58.901Z',
_publishedAt: '2025-04-24T16:26:58.901Z',
}
}
```
### Example `sync-tag-invalidate` event
```javascript
{
data: {
syncTags: ['s1:1023', 's3:3021']
}
}
```
## Example handler
**index.ts (TypeScript)**
```
import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
console.log("Context: ", context)
console.log("Event: ", event)
})
```
**index.js (JavaScript)**
```javascript
export async function handler({context, event}) {
console.log("Context: ", context)
console.log("Event: ", event)
}
```
## Type support
When you create a new TypeScript function with `sanity blueprint add`, you'll be prompted to add types.
If you did not add types as part of the init process, they are available in the [@sanity/functions](https://www.npmjs.com/package/@sanity/functions) package:
**npm**
```shell
npm install -D @sanity/functions
```
**pnpm**
```shell
pnpm add -D @sanity/functions
```
**yarn**
```shell
yarn add --dev @sanity/functions
```
**bun**
```shell
bun add --dev @sanity/functions
```
You can then import and use the `documentEventHandler` helper to provide type support. See the example TS handler above for implementation details.
### Basic usage
Import `documentEventHandler`.
**index.ts**
```
import {documentEventHandler} from '@sanity/functions'
export const handler = documentEventHandler(async ({context, event}) => {
// Your function implementation
console.log('Document updated:', event.data)
})
```
### Pass type for event data
If you need to type `event.data`, and you know the shape of your incoming data, you can provide it to `documentEventHandler`.
**index.ts**
```
import {documentEventHandler} from '@sanity/functions'
interface NotificationData {
documentId: string
text: string
}
export const handler = documentEventHandler(async ({event}) => {
console.log(event.data.text) // Typed as `string`
console.log(event.data.notSet) // Will yield type error
})
```
### Type only (TypeScript)
Import the `DocumentEventHandler` type.
**index.ts**
```
import {type DocumentEventHandler} from '@sanity/functions'
export const handler: DocumentEventHandler = async ({context, event}) => {
// …
}
// …you can also define the data type:
export const handler: DocumentEventHandler<{text: string}> = async ({event}) => {
console.log(event.data.text)
}
```
### Type only (JavaScript)
Use the `@type` comment syntax.
**index.js**
```javascript
/** @type {import('@sanity/functions').DocumentEventHandler} */
export const handler = async ({context, event}) => {
console.log(event.data.text)
}
// …you can also define the data type:
/** @type {import('@sanity/functions').DocumentEventHandler<{text: string}>} */
export const handler = async ({event}) => {
console.log(event.data.text)
}
```
# Function CLI commands
The `functions` CLI command enables managing and testing functions. It's used alongside the `blueprints` command to create and deploy functions.
[Functions introduction](https://www.sanity.io/docs/functions/functions-introduction)
Learn how to take advantage of Functions in your Sanity projects.
[Blueprints introduction](https://www.sanity.io/docs/blueprints/blueprints-introduction)
Learn what Blueprints are, how they work, and how to get started.
**npm**
```shell
npx sanity functions --help
```
**pnpm**
```shell
pnpm dlx sanity functions --help
```
**yarn**
```shell
yarn dlx sanity functions --help
```
**bun**
```shell
bunx sanity functions --help
```
## Commands
### `add`
**CLI output**
```sh
USAGE
$ sanity functions add [--install] [-n ] [--example ] [--helpers] [--installer ] [--javascript] [--json] [--language ] [--type ]
FLAGS
-i, --install Shortcut for --installer npm
-n, --name= Name of the Function to add
--example= Example to use for the Function
--helpers Add helpers to the new Function
--installer= How to install the @sanity/functions helpers
--javascript Use JavaScript instead of TypeScript
--json Format output as json
--language= Language of the new Function
--type= Document change event(s) that should trigger the function; you can specify multiple events by specifying this flag multiple times
DESCRIPTION
Scaffolds a new Function in the functions/ folder and templates a resource for your Blueprint manifest.
Functions are serverless handlers triggered by document, live content or media-library events (create, update, delete, publish).
After adding, use 'functions dev' to test locally, then 'blueprints deploy' to publish.
EXAMPLES
$ sanity functions add
$ sanity functions add --helpers
$ sanity functions add --name my-function
$ sanity functions add --name my-function --type document-create
$ sanity functions add --name my-function --type document-create --type document-update --lang js
```
### `dev`
**CLI output**
```sh
USAGE
$ sanity functions dev [-h ] [-p ] [-t ] [--json]
FLAGS
-h, --host= The local network interface at which to listen. [default: "localhost"]
-p, --port= TCP port to start emulator on. [default: 8080]
-t, --timeout= Maximum execution time for all functions, in seconds. Takes precedence over function-specific `timeout`
--json Format output as json
DESCRIPTION
Runs a local, web-based development server to test your functions before deploying.
Open the emulator in your browser to interactively test your functions with the payload editor.
Optionally, set the host and port with the --host and --port flags. Port 8974 is reserved for the emulator's live-reload WebSocket server. Function timeout can be configured with the --timeout flag.
To invoke a function with the CLI, use 'functions test'.
EXAMPLES
$ sanity functions dev --host 127.0.0.1 --port 3333
$ sanity functions dev --timeout 60
```
### `env`
#### `add`
**CLI output**
```sh
USAGE
$ sanity functions env add NAME KEY VALUE [--json] [--stack ]
ARGUMENTS
NAME The name of the Sanity Function
KEY The name of the environment variable
VALUE The value of the environment variable
FLAGS
--json Format output as json
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Sets an environment variable in a deployed Sanity Function. If the variable already exists, its value is updated.
Environment variables are useful for API keys, configuration values, and other secrets that shouldn't be hardcoded. Changes take effect on the next function invocation.
EXAMPLES
$ sanity functions env add MyFunction API_URL https://api.example.com/
$ sanity functions env add --stack MyFunction API_URL https://api.example.com/
```
#### `list`
**CLI output**
```sh
USAGE
$ sanity functions env list NAME [--json] [--stack ]
ARGUMENTS
NAME The name of the Sanity Function
FLAGS
--json Format output as json
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Displays all environment variables (keys only) configured in a deployed Sanity Function.
Use 'functions env add' to set variables or 'functions env remove' to delete them.
EXAMPLES
$ sanity functions env list MyFunction
$ sanity functions env list --stack MyFunction
```
#### `remove`
**CLI output**
```sh
USAGE
$ sanity functions env remove NAME KEY [--json] [--stack ]
ARGUMENTS
NAME The name of the Sanity Function
KEY The name of the environment variable
FLAGS
--json Format output as json
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Deletes an environment variable from a deployed Sanity Function. The change takes effect on the next function invocation.
Use 'functions env list' to see current variables before removing.
EXAMPLES
$ sanity functions env remove MyFunction API_URL
$ sanity functions env remove --stack MyFunction API_URL
```
### `logs`
**CLI output**
```sh
USAGE
$ sanity functions logs [NAME] [--delete] [--force] [-l ] [--utc] [--watch] [--json] [--stack ]
ARGUMENTS
[NAME] The name of the Sanity Function
FLAGS
-d, --delete Delete all logs for the function
-f, --force Skip confirmation for deleting logs
-l, --limit= Total number of log entries to retrieve
-u, --utc Show dates in UTC time zone
-w, --watch Watch for new logs (streaming mode)
--json Format output as json
--stack= Stack name or ID to use instead of the locally configured Stack
DESCRIPTION
Fetches execution logs from a deployed function, useful for debugging production issues or monitoring activity.
Use --watch (-w) to stream logs in real-time. Use --delete to clear all logs for a function (requires confirmation unless --force is specified).
EXAMPLES
$ sanity functions logs
$ sanity functions logs --json
$ sanity functions logs --limit 100
$ sanity functions logs --delete
```
### `test`
**CLI output**
```sh
USAGE
$ sanity functions test [NAME] [-a ] [-d ] [-e ] [-f ] [-t ] [--data-after ] [--data-before ] [--dataset ] [--document-id ] [--document-id-after