How the prerelease works

Prerelease status for Editorial Workflows: versioning under 0.x, where workflow data lives, what guards enforce today, and who runs the effect runtime.

Editorial Workflows is a prerelease. Keep every @sanity/workflow-* package used by one application on the same version. Review release notes and required migrations before upgrading, and upgrade every reader before deploying a writer that requires a newer reader model.

The public Editorial Workflows packages release as one fixed stack. Their shared runtime dependencies are exact-version peers, so install the packages your application uses explicitly and keep their versions identical. Packages remain on 0.x: breaking API changes use minor releases and are listed in the release notes and package changelogs.

Persisted workflow documents have a stricter contract than the package APIs: stored shapes grow additively, and reader-floor changes require a reader-first rollout rather than discarding in-flight instances.

Set a reviewed expectedMinReaderModel literal on every deployment. Engine 0.22 still requires the literal 4. The numeric type lets stale literals reach the runtime compatibility check, which rejects them with readers-first rollout guidance. This is a deployment acknowledgement, not a createEngine option.

• Keep the value literal. Do not import DATA_MODEL_MIN_READER, because a dependency upgrade must not silently acknowledge a higher floor.

Upgrade every Studio, CLI, MCP server, Function, server, and application that reads the workflow resource. Upgrade the producer and deploy definitions last.

Model 4 changes readiness storage and live principal identity. Existing live identity values resolve through the project directory and are rewritten on their next engine commit. History remains unchanged.

// sanity.workflow.ts
import {defineWorkflowConfig} from '@sanity/workflow-engine/define'
import {myWorkflow} from './workflow'

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

For a direct engine deployment, acknowledge the same reader model:

import {engine} from './engine'
import {myWorkflow} from './workflow'

await engine.deployDefinitions({
  expectedMinReaderModel: 4,
  definitions: [myWorkflow],
})

During the prerelease, each deployment chooses where its engine-owned state lives.

• Definitions and instances: stored as Sanity documents in the deployment’s workflowResource. A dedicated dataset is common, but the configured resource is the authority.
• Deployment partitions: every definition and instance carries the deployment tag. Different tags can share one workflow resource without sharing workflow state.
• Organization-wide content: a workflow can coordinate documents across datasets, projects, and resource types such as Canvas and Media Library. The content remains in its original resource; workflow fields hold global document references to it. The deployment’s credentials and resource routing must be able to reach every referenced resource.

See Where the workflow lives for the deployment configuration.

No different managed storage destination is part of the public contract today. Treat workflowResource as the prerelease storage contract; if that changes, the release notes will include the destination and migration steps.

Workflow guards let engine-aware surfaces preview holds and explain denied engine commits. See Guards and enforcement for the current enforcement boundary and deployment behavior.

Effects are queued by the engine and completed by a drainer you operate: a Sanity Function, a server, or the CLI during development. Nothing drains automatically. Follow Drive it with a Function for a complete drain-and-tick implementation.

The Studio plugin requires Sanity 6.3 or later. Use autoStart for fresh documents, and review the Editorial Workflows release notes before upgrading.

sanity-workflows nuke deletes a deployment's definitions, instances, and guards. Use it only when intentionally abandoning that workflow state. For disposable prerelease data, reset after upgrading and redeploy model 4 definitions; otherwise preserve existing instances and let live identities self-heal.