Workflows

Workflows own durable long-running execution. Use them when work needs a Workflow Run, provider-tracked state, retries, resumability, or optional Workflow Steps.

Workflow is not Queue. Queue delivers jobs; Workflow starts and tracks a run.

Quick start

pnpm add @vite-hub/workflow

import { hubWorkflow } from '@vite-hub/workflow/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubWorkflow()],
})

import { defineWorkflow } from '@vite-hub/workflow'

export default defineWorkflow<{ email: string }>(async ({ payload }) => {
  return createUser(payload.email)
})

import { runWorkflow } from '@vite-hub/workflow'

export default defineEventHandler(async () => {
  return runWorkflow('onboard-user', { email: 'ada@example.com' })
})

Public imports

Workflow Provider, Definition, Run, Step, Start Options, and Integration Options types are exported from @vite-hub/workflow.

Configure the Vite Integration

import { hubWorkflow } from '@vite-hub/workflow/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [hubWorkflow()],
})

The Vite config key is workflow.

When no provider is configured, ViteHub selects Cloudflare on Cloudflare hosting and Vercel otherwise. On Node or Docker hosting, OpenWorkflow is inferred when OpenWorkflow storage is configured through database, postgres.url, or sqlite.path.

Providers

Define a workflow

Create a Workflow Definition for named long-running work.

import { defineWorkflow } from '@vite-hub/workflow'

export default defineWorkflow<{ email: string }>(async ({ payload }) => {
  const user = await createUser(payload.email)
  await sendWelcomeEmail(user.email)

  return { userId: user.id }
})

Use Workflow Steps only when the selected provider and definition need independently retryable or inspectable units.

Workflow Definition options

defineWorkflow(handler, options?) accepts these options. The discovered file name provides the Definition name.

The handler receives a WorkflowExecutionContext with name, payload, provider, optional run id, and provider-backed step or typed steps helpers when available.

Start a run

Use runWorkflow() from server code.

import { runWorkflow } from '@vite-hub/workflow'

export default defineEventHandler(async (event) => {
  const body = await readBody<{ email: string }>(event)

  return runWorkflow('onboard-user', body, {
    id: `onboard:${body.email}`,
  })
})

The run id belongs to Invocation Options. Use a stable id when the provider should dedupe or resume the same logical run.

Runtime Helpers

WorkflowStartOptions currently accepts id.

Workflow Run shape

Inspect a run

Use getWorkflowRun() when server code needs current run state.

import { getWorkflowRun } from '@vite-hub/workflow'

export default defineEventHandler((event) => {
  return getWorkflowRun('onboard-user', getRouterParam(event, 'id')!)
})

Connect it to Agents

An Agent can start a workflow only when you explicitly expose that behavior through a Capability or server route. Workflow owns durable orchestration; Agent owns model-backed behavior and Agent Invocations.

Use a product-specific Capability when a model should start or inspect a particular Workflow Run.

Production boundaries

Use Queue when background delivery is enough. Use Workflow when the app must inspect run state, resume work, or coordinate multiple steps over time.

Keep credentials and database URLs in Server Env. Hosted workflow providers may require explicit state storage or deployment setup.

Next steps

• Use Queue for simple background delivery.
• Trigger recurring work with Schedule.
• Learn shared runtime events in Runtime policy, approvals, and traces.