Getting Started

Overview

Workflow Studio is an additive overlay package for Vercel Workflow that enables remote compute and composable topology.

Installation

npm install workflow-studio
## or
pnpm add workflow-studio
## or
yarn add workflow-studio

Configuration

Basic Setup (Local Execution)

Create a workflow.config.ts in your project root:

workflow.config.ts

import {
  createPostgresQueueAdapter,
  createRedisStreamAdapter,
  defineWorkflowStudioConfig,
} from 'workflow-studio';

export default defineWorkflowStudioConfig({
  queue: createPostgresQueueAdapter({
    connectionString: process.env.DATABASE_URL,
  }),
  streams: createRedisStreamAdapter({
    url: process.env.REDIS_URL,
  }),
  execution: {
    mode: 'local', // default
  },
});

Remote Execution Setup

For production remote execution:

workflow.config.ts

import {
  createPostgresQueueAdapter,
  createRedisStreamAdapter,
  defineWorkflowStudioConfig,
} from 'workflow-studio';

export default defineWorkflowStudioConfig({
  queue: createPostgresQueueAdapter({
    connectionString: process.env.DATABASE_URL,
  }),
  streams: createRedisStreamAdapter({
    url: process.env.REDIS_URL,
  }),
  execution: {
    mode: 'remote',
    remoteWorkerUrl: process.env.WORKFLOW_COMPUTE_BASE_URL,
    apiKeyEnv: 'WORKFLOW_COMPUTE_API_KEY',
    timeoutMs: 10_000,
    retries: 2,
    failPolicy: 'error',
  },
});

Critical Production Configuration

For unchanged start() calls to route to remote execution, you must set this in your deployment environment:

WORKFLOW_TARGET_WORLD=workflow-studio/world-remote

This environment variable is the production guarantee that routes all workflow operations to the remote worker. Wrapper configurations alone do not guarantee this behavior.

Artifact deploy vs infrastructure deploy

workflow-studio compute deploy uploads a workflow artifact and manifest to an already-running compute-worker service. It does not deploy your app, VM, container, or cloud infrastructure. Deploy infrastructure with your platform pipeline, then use compute build/deploy/activate/rollback to manage workflow versions inside compute-worker.

Environment Variables

Variable	Description	Required For
`WORKFLOW_COMPUTE_BASE_URL`	Remote worker base URL	Remote mode
`WORKFLOW_COMPUTE_API_KEY`	API key for worker authentication	Remote mode
`WORKFLOW_TARGET_WORLD`	Must be `workflow-studio/world-remote`	Production remote
`WORKFLOW_EXECUTION_MODE`	`local` or `remote` (override)	Optional
`WORKFLOW_EXECUTION_FAIL_POLICY`	`error` or `fallback-local` (override)	Optional

Invalid values for WORKFLOW_EXECUTION_MODE or WORKFLOW_EXECUTION_FAIL_POLICY fail fast during config resolution.