Was this page helpful?
Reference documentation for the shape of the function wrapper.
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 propertiesProvides 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.
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.
The resource type that triggered the function. For Document functions, this would be dataset. For Media Library functions, this would be media-library.
The resource ID that triggered the function. For Document functions, this would be the ID of a dataset in the form <project-id>.<dataset-name>. For Media Library functions, this would be the Media Library id.
clientOptions propertiesThe ID of the project that triggered this function.
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
Defaults to https://api.sanity.io.
A token provided by the function with access to your Sanity project. This token is automatically generated with the editor role and added to your project when deploying the blueprint.
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.
{
clientOptions: {
apiHost: 'https://api.sanity.io',
projectId: 'abc123',
dataset: 'production',
token: '***************'
}
}event propertiesContains the shape of the event. In the case of document triggers, like publish, the event shape is the document. This will vary based on your schema.
{
data: {
_id: '1234',
_type: 'article',
title: 'Functions quick start',
_createdAt: '2025-04-24T16:26:58.901Z',
_publishedAt: '2025-04-24T16:26:58.901Z',
}
}import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
console.log("Context: ", context)
console.log("Event: ", event)
})export async function handler({context, event}) {
console.log("Context: ", context)
console.log("Event: ", event)
}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 package:
npm install -D @sanity/functions
pnpm add -D @sanity/functions
yarn add --dev @sanity/functions
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.
Import documentEventHandler.
import {documentEventHandler} from '@sanity/functions'
export const handler = documentEventHandler(async ({context, event}) => {
// Your function implementation
console.log('Document updated:', event.data)
})If you need to type event.data, and you know the shape of your incoming data, you can provide it to documentEventHandler.
import {documentEventHandler} from '@sanity/functions'
interface NotificationData {
documentId: string
text: string
}
export const handler = documentEventHandler<NotificationData>(async ({event}) => {
console.log(event.data.text) // Typed as `string`
console.log(event.data.notSet) // Will yield type error
})Import the DocumentEventHandler type.
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)
}Use the @type comment syntax.
/** @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)
}{
clientOptions: {
apiHost: 'https://api.sanity.io',
projectId: 'abc123',
dataset: 'production',
token: '***************'
}
}{
data: {
_id: '1234',
_type: 'article',
title: 'Functions quick start',
_createdAt: '2025-04-24T16:26:58.901Z',
_publishedAt: '2025-04-24T16:26:58.901Z',
}
}import { documentEventHandler } from '@sanity/functions'
export const handler = documentEventHandler(async ({ context, event }) => {
console.log("Context: ", context)
console.log("Event: ", event)
})export async function handler({context, event}) {
console.log("Context: ", context)
console.log("Event: ", event)
}npm install -D @sanity/functionspnpm add -D @sanity/functionsyarn add --dev @sanity/functionsbun add --dev @sanity/functionsnpm install -D @sanity/functionspnpm add -D @sanity/functionsyarn add --dev @sanity/functionsbun add --dev @sanity/functionsimport {documentEventHandler} from '@sanity/functions'
export const handler = documentEventHandler(async ({context, event}) => {
// Your function implementation
console.log('Document updated:', event.data)
})import {documentEventHandler} from '@sanity/functions'
interface NotificationData {
documentId: string
text: string
}
export const handler = documentEventHandler<NotificationData>(async ({event}) => {
console.log(event.data.text) // Typed as `string`
console.log(event.data.notSet) // Will yield type error
})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 {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)
}