Sanity Best Practices

my-project/
├── studio/
├── next-app/
├── functions/
│   ├── my-function/
│   │   ├── index.ts          # Handler code (entry point)
│   │   └── package.json      # (optional) function-level dependencies
│   └── another-function/
│       └── index.ts
├── sanity.blueprint.ts        # Blueprint configuration
├── package.json               # Project-level dependencies
└── node_modules/

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

npx sanity@latest functions add \
  --name my-function \
  --type document-create --type document-update \
  --installer npm

// sanity.blueprint.ts
import { defineBlueprint, defineDocumentFunction } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineDocumentFunction({
      name: 'my-function',
      event: {
        on: ['create', 'update'],
        // The handler patches the same document, which emits another update
        // event. Guard with !defined(firstPublished) so the function stops
        // matching once it has run — see "Recursion control" below.
        filter: '_type == "post" && !defined(firstPublished)',
      },
    }),
  ],
})

// functions/my-function/index.ts
import { documentEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'

interface PostData {
  _id: string
  _type: string
  title: string
}

export const handler = documentEventHandler<PostData>(async ({ context, event }) => {
  const { data } = event

  const client = createClient({
    ...context.clientOptions,
    apiVersion: '2025-05-08',
  })

  try {
    await client
      .patch(data._id, {
        setIfMissing: { firstPublished: new Date().toISOString() },
      })
      .commit()
    console.log(`Set firstPublished on ${data._id}`)
  } catch (error) {
    console.error('Failed to patch document:', error)
  }
})

# Visual dev playground
npx sanity@latest functions dev

# CLI testing
npx sanity@latest functions test my-function \
  --dataset production \
  --with-user-token

# With a specific document
npx sanity@latest functions test my-function \
  --document-id abc123 \
  --dataset production \
  --with-user-token

npx sanity@latest blueprints deploy

npx sanity@latest functions logs my-function
npx sanity@latest functions logs my-function --watch

{
  data: {
    _id: string
    _type: string
    // ... rest of document (shaped by projection if set)
  }
}

import { defineBlueprint, defineMediaLibraryAssetFunction } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineMediaLibraryAssetFunction({
      name: 'asset-handler',
      event: {
        on: ['delete'],
        filter: 'documents::incomingGlobalDocumentReferenceCount() > 0',
        projection: '{_id, versions, title}',
        resource: {
          type: 'media-library',
          id: 'mlYourLibraryId',
        },
      },
    }),
  ],
})

import { defineBlueprint, defineSyncTagInvalidateFunction } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineSyncTagInvalidateFunction({
      name: 'invalidate-tags',
      // Scope to one dataset so a shared blueprint doesn't fire against staging
      event: { resource: { type: 'dataset', id: 'myProjectId.production' } },
    }),
  ],
})

// functions/invalidate-tags/index.ts
import { syncTagInvalidateEventHandler } from '@sanity/functions'

export const handler = syncTagInvalidateEventHandler(async ({ context, event, done }) => {
  const { syncTags } = event.data

  if (!context.local) {
    await fetch(process.env.CACHE_PURGE_URL!, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ tags: syncTags }),
    })
  }

  // Signals that invalidation finished. Clients waiting on the Live Content
  // API block until this resolves — skip it and they never see the update.
  await done(syncTags)
})

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 * * *' },   // midnight daily
      timezone: 'America/New_York',          // IANA identifier; defaults to UTC
      robotToken: '$.resources.my-robot.token',
    }),
  ],
})

// functions/expire-cache/index.ts
import { scheduledEventHandler } from '@sanity/functions'
import { createClient } from '@sanity/client'

export const handler = scheduledEventHandler(async ({ context }) => {
  // projectId and dataset are NOT in context here — set them explicitly
  const client = createClient({
    projectId: 'abc123',
    dataset: 'production',
    apiVersion: '2025-05-08',
    token: context.clientOptions?.token,   // from the robotToken above
  })

  const stale = await client.fetch(
    `*[_type == "cacheEntry" && expiresAt < now()]._id`,
  )

  if (!context.local && stale.length) {
    await stale
      .reduce((tx, id) => tx.delete(id), client.transaction())
      .commit()
  }

  console.log(`Expired ${stale.length} entries`)
})

import { defineBlueprint, definePubSubFunction } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    definePubSubFunction({ name: 'slack-post' }),
  ],
})

// functions/slack-post/index.ts
import { pubSubEventHandler } from '@sanity/functions'

export const handler = pubSubEventHandler(async ({ context, event }) => {
  // event.data is whatever the caller passed — validate it, it is not typed
  // or validated by the platform the way a document event is
  const { text } = event.data

  await fetch(process.env.SLACK_WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ text }),
  })
})

// functions/on-publish/index.ts
import { documentEventHandler, invoke } from '@sanity/functions'

export const handler = documentEventHandler(async ({ context, event }) => {
  await invoke('slack-post', {
    context,
    event: { data: { text: `Published ${event.data.title}` } },
  })
})

const result = await invoke('slack-post', { context, event })
if (result.ok) { /* never runs as expected — result is not the callee's return value */ }

// Same mistake, sequenced: this read happens right after the invocation is
// accepted, not after resize-image has resized anything.
await invoke('resize-image', { context, event })
const resized = await client.fetch(`*[_id == $id][0].resizedUrl`, { id: event.data._id })

try {
  await invoke('slack-post', { context, event: { data: event.data } })
} catch (err) {
  // Only failures to *accept* the invocation land here
  console.error('Failed to trigger slack-post:', err)
}

const response = await invoke(
  'validate-content',
  { context, event: { data: event.data } },
  { sync: true },
)

if (!response.valid) return { skipped: true, reason: response.reason }

await invoke('publish-content', { context, event: { data: event.data } })

defineDocumentFunction({
  name: 'first-published',
  event: {
    on: ['create', 'update'],
    filter: "_type == 'post' && !defined(firstPublished)",
  },
})

import { createClient } from '@sanity/client'

// Client automatically sets X-Sanity-Lineage header
// Recursive chains are limited to 16 invocations
const client = createClient({
  ...context.clientOptions,
  apiVersion: '2025-05-08',
})

defineDocumentFunction({
  name: 'update-post',
  event: {
    on: ['create', 'update'],
    filter: "_type == 'post'",  // Will re-trigger on its own writes!
  },
})

// Skip mutations entirely in test
if (!context.local) {
  await client.createOrReplace(someDoc)
}

// Or use dryRun
await client.patch(event.data._id, {
  set: { processed: true },
}).commit({ dryRun: context.local })

// Or use noWrite for Agent Actions
await client.agent.action.generate({
  schemaId: 'your-schema-id',
  documentId: event.data._id,
  instruction: 'Summarize this document',
  target: { path: ['summary'] },
  noWrite: context.local,
})

defineDocumentFunction({
  name: 'deploy-hook',
  event: {
    on: ['create', 'update'],
    filter: '_type == "page"',
  },
})

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')

  await fetch(URL)
  console.log('Deploy hook triggered')
})

defineDocumentFunction({
  name: 'first-published',
  event: {
    on: ['create', 'update'],
    filter: '_type == "post" && !defined(firstPublished)',
  },
})

defineDocumentFunction({
  name: 'translate',
  event: {
    on: ['create', 'update'],
    filter: "_type == 'post' && language == 'en-US'",
    projection: '{_id}',
  },
})

export const handler = documentEventHandler(async ({ context, event }) => {
  const client = createClient({ ...context.clientOptions, apiVersion: 'vX' })

  await client.agent.action.translate({
    schemaId: 'your-schema-id',
    async: true,
    documentId: event.data._id,
    languageFieldPath: 'language',
    targetDocument: {
      operation: 'create',
    },
    fromLanguage: { id: 'en-US', title: 'English' },
    toLanguage: { id: 'el-GR', title: 'Greek' },
  })
})

defineDocumentFunction({
  name: 'auto-tag',
  event: {
    on: ['create', 'update'],
    // Only fire while tags are missing. The handler writes to `tags`, which
    // emits another `update` event — without this guard the function would
    // re-trigger itself in a loop. Once tags exist, the filter stops matching.
    filter: "_type == 'post' && !defined(tags)",
    projection: '{_id, title, body}',
  },
})

export const handler = documentEventHandler(async ({ context, event }) => {
  const client = createClient({ ...context.clientOptions, apiVersion: 'vX' })

  await client.agent.action.generate({
    schemaId: 'your-schema-id',
    documentId: event.data._id,
    instruction: 'Analyze the content and generate 3 relevant tags. Reuse existing tags when possible.',
    target: { path: ['tags'] },
    async: true,
  })
})

export const handler = documentEventHandler(async ({ context, event }) => {
  const WEBHOOK_URL = process.env.SLACK_WEBHOOK_URL
  if (!WEBHOOK_URL) throw new Error('SLACK_WEBHOOK_URL not set')

  await fetch(WEBHOOK_URL, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      text: `📝 New content published: *${event.data.title || event.data._id}* (${event.data._type})`,
    }),
  })
})

export default defineBlueprint({
  resources: [
    defineDocumentFunction({
      name: 'on-publish',
      event: { on: ['create', 'update'], filter: "_type == 'post'" },
    }),
    definePubSubFunction({ name: 'post-to-bluesky' }),
    definePubSubFunction({ name: 'post-to-linkedin' }),
    definePubSubFunction({ name: 'post-to-mastodon' }),
  ],
})

import { documentEventHandler, invoke } from '@sanity/functions'

export const handler = documentEventHandler(async ({ context, event }) => {
  await Promise.all([
    invoke('post-to-bluesky', { context, event }),
    invoke('post-to-linkedin', { context, event }),
    invoke('post-to-mastodon', { context, event }),
  ])
})

defineDocumentFunction({
  name: 'production-only',
  event: {
    on: ['update'],
    filter: "_type == 'post'",
    resource: { type: 'dataset', id: 'myProjectId.production' },
  },
})

defineDocumentFunction({
  name: 'production-only',
  event: {
    on: ['update'],
    filter: "_type == 'post' && sanity::dataset() == 'production'",
  },
})

import { defineBlueprint, defineMediaLibraryAssetFunction } from '@sanity/blueprints'

export default defineBlueprint({
  resources: [
    defineMediaLibraryAssetFunction({
      name: 'asset-deleted',
      event: {
        on: ['delete'],
        filter: 'documents::incomingGlobalDocumentReferenceCount() > 0',
        projection: '{_id, versions, title}',
        resource: { type: 'media-library', id: 'mlYourLibraryId' },
      },
    }),
  ],
})

export const handler = documentEventHandler(async ({ context, event }) => {
  const { eventResourceId } = context  // Media Library ID
  const client = createClient({
    ...context.clientOptions,
    apiVersion: '2025-05-08',
  })

  const response = await client.request({
    uri: `/media-libraries/${eventResourceId}/query`,
    method: 'POST',
    body: { query: `*[_type == 'sanity.imageAsset']` },
  })

  console.log('Assets:', response)
})

export const handler = documentEventHandler(async ({ context, event }) => {
  const lineage = process.env.X_SANITY_LINEAGE

  await fetch(`https://${context.clientOptions.projectId}.api.sanity.io/v2025-05-08/data/mutate/${context.clientOptions.dataset}`, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'Authorization': `Bearer ${context.clientOptions.token}`,
      ...(lineage ? { 'X-Sanity-Lineage': lineage } : {}),
    },
    body: JSON.stringify({
      mutations: [{ patch: { id: event.data._id, set: { processed: true } } }],
    }),
  })
})

export default defineBlueprint({
  resources: [
    defineDocumentFunction({
      name: 'first-published',
      event: {
        on: ['create', 'update'],
        filter: "_type == 'post' && !defined(firstPublished)",
      },
    }),
    defineDocumentFunction({
      name: 'notify-slack',
      event: {
        on: ['create', 'update'],
        filter: "_type == 'post'",
        projection: '{title, _id}',
      },
    }),
    defineDocumentFunction({
      name: 'sync-algolia',
      timeout: 30,
      event: {
        on: ['create', 'update', 'delete'],
        filter: "_type == 'product'",
      },
    }),
  ],
})

- uses: sanity-io/blueprints-actions/deploy@deploy-v3
  with:
    sanity-token: ${{ secrets.SANITY_DEPLOY_TOKEN }}