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.
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 provided by the function with access to your Sanity project. This token is automatically generated with the
editorrole and added to your project when deploying the blueprint.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. In the case of document triggers, like publish, the event shape is the document. This will vary based on your schema.
Example 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 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/functionsYou 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:', 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)
}Was this page helpful?