Set up the Studio plugin

Install the Editorial Workflows plugin for Sanity Studio and use document controls and cross-document workflow tasks.

The Studio plugin connects deployed Editorial Workflows to Sanity Studio. It gives editors document-level workflow controls and a cross-document view of current work.

The plugin turns deployed workflow definitions into an editor-facing workflow experience inside Studio.

• Document workflow controls: start a workflow, see its current stage, and open its current work.
• Activities and actions: complete tasks, edit workflow fields, and fire available actions.
• Cross-document tasks: find active work in the Workflows tool, including assignments for the current editor.
• Automatic starts: start selected workflows when an editor creates a document.
• Workflow-aware document actions: explain holds before an editor publishes, unpublishes, or deletes.

Use Sanity Studio 6.3 or later. Install matching versions of every @sanity/workflow-* package in the Studio.

Install the packages in an existing Studio v6 project. The plugin reads definitions deployed with the CLI and authored with the engine.

npm install @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli

pnpm add @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli

yarn add @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli

bun add @sanity/workflow-studio-plugin @sanity/workflow-components @sanity/workflow-diagram @sanity/workflow-engine @sanity/workflow-react @sanity/workflow-sdk @sanity/workflow-studio @sanity/workflow-cli

If nothing is deployed yet, do that first: Set up the workflow CLI covers the config and the deploy, and Getting started walks the whole path.

In sanity.config.ts, register the Workflows document view and add the plugin with the tag used to deploy the definitions.

import {defineConfig} from 'sanity'
import {structureTool} from 'sanity/structure'
import {
  workflowDefaultDocumentNode,
  workflowStudioPlugin,
} from '@sanity/workflow-studio-plugin'

export default defineConfig({
  // ...your projectId, dataset, schema...
  plugins: [
    structureTool({
      defaultDocumentNode: workflowDefaultDocumentNode(),
    }),
    workflowStudioPlugin({
      tag: 'production', // must match the deploy tag
    }),
  ],
})

A workflow’s subject field identifies the primary document it governs and declares the document types it accepts. When the caller supplies that subject at start, the plugin can discover the matching deployed workflows without extra configuration.

A mapping connects one Studio document type to one deployed workflow definition. Subject-based discovery creates that connection automatically; add a mapping only when you need to override or extend it:

• Enable autoStart for one workflow.
• Bind a definition that uses doc.ref instead of a first-class subject.
• Customize its label, workflow context, or Content Release perspective.

Several workflows may target one document type. Duplicate rows for the same document-type and definition pair are rejected.

Declare start values with field initial values in the workflow definition. Studio supplies the mapped subject and renders controls for the remaining workflow-scoped input fields.

These options control where the plugin reads workflow state and how it integrates with the Studio.

• tag must match the tag used to deploy the definitions.
• workflowDataset stores workflow data in a dedicated dataset.
• resourceClients provides clients for documents in other datasets, projects, or resources.
• mappings customizes discovered document-type and definition pairs, enables auto-start, or binds legacy doc.ref definitions.
• effectHandlers runs selected effects while an editor is present. Use a server runtime for unattended or consequential work.

Open a document accepted by a deployed workflow. The plugin brings the workflow into the document editor in three places:

• Workflow strip: start an available workflow and see the current stage above the document form.
• Workflows view: work through the stage’s activities, editable fields, and actions.
• Document badges: see the active workflow and whether the document belongs to a draft or Content Release.

Use autoStart on a mapping row to start that workflow when an editor creates a document in Studio. Existing documents and writes outside Studio are unaffected.

Add one mapping row for each workflow that should start automatically. A mapping identifies one document type and deployed definition; several rows may target the same document type.

workflowStudioPlugin({
  tag: 'production',
  mappings: [
    {
      docType: 'article',
      definition: 'article-review',
      label: 'Article review',
      autoStart: true,
    },
  ],
})

Auto-start applies only to fresh documents created in Studio:

• The new document becomes the workflow subject in the same draft or Content Release perspective.
• Required start inputs are collected before the editor enters the form.
• If several workflows apply, Studio starts them independently and retries only those that failed.
• Writes outside Studio bypass auto-start; it is an integration convenience, not an enforcement boundary.

The tool groups current work by document. When a local subject document is deleted, it confirms the document is still absent before offering to abort the orphaned workflow instances. Restored, foreign, unreadable, or uncertain documents are left alone.

The Workflows tool collects current workflow work across documents:

• Current work: browse active tasks across documents.
• For me: narrow the list to activities assigned to the current editor.
• Workflow details: open a workflow to inspect and act on its current stage.

When a workflow guard denies publishing, unpublishing, or deleting a document, the plugin disables that Studio action and explains the hold.

These holds are advisory. The Content Lake remains the enforcement boundary; see Guards and enforcement.

Studio advances workflows while editors are present. Time-based transitions and queued effects need a runtime; see Effects and runtimes.

• Custom Studio integrations: build your own workflow controls inside Studio.
• Getting started: the shortest path from nothing to a running workflow.
• Set up the workflow CLI: deploy the definitions the plugin surfaces.
• Effects and runtimes: how queued effects run and where the runtime lives.
• Reference: every construct spelled out exactly, each field, type, default, and option.