Getting started

Define your first workflow in TypeScript, deploy it, and move a Sanity document through its stages.

The workflow engine runs workflows you define in TypeScript against your Sanity documents. In this guide, you will deploy a three-stage workflow and move an article from drafting to review to published.

Install the workflow engine, the Sanity client, and the workflow CLI in your project:

npm install @sanity/workflow-engine @sanity/client
npm install -D @sanity/workflow-cli

pnpm add @sanity/workflow-engine @sanity/client
pnpm add -D @sanity/workflow-cli

yarn add @sanity/workflow-engine @sanity/client
yarn add --dev @sanity/workflow-cli

bun add @sanity/workflow-engine @sanity/client
bun add --dev @sanity/workflow-cli

Keep @sanity/workflow-engine and @sanity/workflow-cli on the same version. All public Editorial Workflows packages used by one application must come from the same release.

Create article-review-workflow.ts. The workflow starts in drafting. Completing the activity in each stage moves the instance to the next stage.

// article-review-workflow.ts
import {
  defineAction,
  defineActivity,
  defineField,
  defineStage,
  defineTransition,
  defineWorkflow,
} from '@sanity/workflow-engine/define'

export const articleReview = defineWorkflow({
  name: 'article-review',
  title: 'Article review',
  initialStage: 'drafting',
  fields: [
    defineField({
      type: 'subject',
      name: 'subject',
      required: true,
      initialValue: {type: 'input'},
    }),
  ],
  stages: [
    defineStage({
      name: 'drafting',
      activities: [
        defineActivity({
          name: 'write',
          actions: [defineAction({name: 'submit', status: 'done'})],
        }),
      ],
      transitions: [defineTransition({name: 'to-review', to: 'review'})],
    }),
    defineStage({
      name: 'review',
      activities: [
        defineActivity({
          name: 'sign-off',
          actions: [defineAction({name: 'approve', status: 'done'})],
        }),
      ],
      transitions: [defineTransition({name: 'to-published', to: 'published'})],
    }),
    defineStage({name: 'published'}),
  ],
})

The required subject field connects each workflow instance to the document it is about. Its value is a global document reference, so the document keeps its project, dataset, or other resource identity.

The workflow has three stages: drafting, review, and published.

Firing submit completes the writing activity and moves the instance to review. Firing approve completes sign-off and moves it to published.

For more about these building blocks, see Concepts and Activities and actions.

Create sanity.workflow.ts beside the workflow definition. It tells the CLI which definitions to deploy and where the engine should store definitions and instances.

// sanity.workflow.ts
import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
import {articleReview} from './article-review-workflow'

export default defineWorkflowConfig({
  deployments: [
    {
      name: 'default',
      tag: 'default',
      expectedMinReaderModel: 4,
      workflowResource: {
        type: 'dataset',
        id: 'yourprojectid.production',
      },
      definitions: [articleReview],
    },
  ],
})

Replace yourprojectid and production with your project ID and dataset. expectedMinReaderModel: 4 is a reviewed acknowledgement that every engine-backed reader in your deployment can read the model this writer emits—not a number to guess or increment independently. Upgrade readers before writers; see Reader-model acknowledgement. Then log in and deploy:

sanity login
pnpm sanity-workflows deploy

When the command reports that article-review was created, the workflow is deployed and ready to run. For authentication, tags, and multiple environments, see Set up the workflow CLI.

Choose a document in the dataset and note its ID and schema type. The example below starts the workflow for an article with the ID article-123; replace both values with your own.

pnpm sanity-workflows start article-review \
  --field subject='{"id":"dataset:yourprojectid:production:article-123","type":"article"}'

The start command creates an instance in drafting and prints its instance ID. Copy that ID, then fire the two actions:

# Move from drafting to review
pnpm sanity-workflows fire-action INSTANCE_ID \
  --activity write \
  --action submit

# Move from review to published
pnpm sanity-workflows fire-action INSTANCE_ID \
  --activity sign-off \
  --action approve

# Confirm the final stage
pnpm sanity-workflows list --include-completed

• Replace INSTANCE_ID with the ID returned by the start command.
• If you want to see which actions are currently available, run pnpm sanity-workflows fire-action INSTANCE_ID without an activity or action.
• If the list shows the instance in published, your first Editorial Workflow is running.

The CLI is the shortest path to a running workflow. To operate the same deployed instance from your application, create an engine with a write-enabled Sanity client:

import {createClient} from '@sanity/client'
import {
  createEngine,
  ENGINE_API_VERSION,
  refDataset,
} from '@sanity/workflow-engine'

const client = createClient({
  projectId: 'yourprojectid',
  dataset: 'production',
  apiVersion: ENGINE_API_VERSION,
  token: process.env.SANITY_AUTH_TOKEN,
  useCdn: false,
})

const engine = createEngine({
  client,
  workflowResource: {
    type: 'dataset',
    id: 'yourprojectid.production',
  },
  tag: 'default',
})

const {instance} = await engine.startInstance({
  definition: 'article-review',
  initialFields: [
    {
      type: 'subject',
      name: 'subject',
      value: refDataset({
        projectId: 'yourprojectid',
        dataset: 'production',
        documentId: 'article-123',
        type: 'article',
      }),
    },
  ],
})

await engine.fireAction({
  instanceId: instance._id,
  activity: 'write',
  action: 'submit',
})

To view and operate the workflow alongside your document, use a Sanity Studio v6 project, install @sanity/workflow-studio-plugin, and map your article type to the deployed article-review definition. See Set up the Studio plugin.

The workflow strip above the document form shows the current stage. The Workflows view lists its activities and available actions.

You can open the workflow in a structure view beside the document editor.

• Cookbook: Editorial review: add approval data, change requests, and a review loop.
• Cross-resource workflows: coordinate content across projects, datasets, Canvas, and Media Library.
• Concepts: understand definitions, instances, stages, fields, and transitions.
• Set up the workflow CLI: configure authentication, resources, tags, and multiple deployments.
• Test your workflows: run a workflow in memory before deploying it.
• Reference: look up every construct and engine verb.