Function handler reference
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 properties
clientOptionsobject
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/clientin Functions guide for details.localboolean
The
context.localvalue is set totruefor functions invoked withsanity functions testandsanity functions dev. This can be helpful when you want code to only execute in local environments.It is
undefinedfor functions in production.eventResourceTypestring
The resource type that triggered the function. For Document functions, this would be
dataset. For Media Library functions, this would bemedia-library.eventResourceIdstring
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 properties
projectIdstring
The ID of the project that triggered this function.
datasetstring
The dataset name of the project that triggered this function.
The
sanity functions testcommand won't include a dataset by default. Run with the--datasetflag to pass a dataset toclientOptions. For example:sanity functions test log-event --dataset productionapiHoststring
Defaults to
https://api.sanity.io.tokenstring
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.documentFunctions, this token is automatically generated with theeditorrole 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 testcommand won't include a token by default. Run with the--with-user-tokenflag 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
{
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
documentandmedia-libraryFunction events, likepublish, the event shape is the document. This will vary based on your schema. - In the case of
sync-tag-invalidateFunction events, the sync tags will be present underevent.data.syncTags.
Example document event
{
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
{
data: {
syncTags: ['s1:1023', 's3:3021']
}
}Example handler
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)
}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 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.
Basic usage
Import documentEventHandler.
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.
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
})Type only (TypeScript)
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)
}Type only (JavaScript)
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)
}