Create a Sync Tag Invalidate Function

Build and deploy a new Sync Tag Invalidate function to Sanity's infrastructure.

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.

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 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 (the deployStudio grant).

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

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:

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 <project-id> with your project ID, found in manage or your sanity.config.ts file.

npx sanity@latest blueprints init . --type ts --stack-name production --project-id <project-id>

This configures a new blueprint for your project, adds a sanity.blueprint.ts config file to the current directory (.), and creates a new stack named production.

Follow the prompt and run your package manager’s install command to add the dependencies.

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

npx sanity@latest functions add --name invalidate-tags --type sync-tag-invalidate --installer npm

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:

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.

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.

If you've followed the directory structure mentioned earlier, you'll see it grow to something like this:

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.

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.

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.

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.

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

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

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

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 and the functions CLI reference.

Deploy a function

Once you're satisfied that the function works as expected, deploy it by deploying the blueprint stack.

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

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

  • Remove the definition from the blueprint, and run the deploy command again.
  • 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. 

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

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

Was this page helpful?

Previous

Create a Media Library Asset Function

Next

Create a Scheduled Function