Workflow

Use Workflow to run durable server-side processes that can pause, retry, checkpoint, and outlive a single request.

Getting started

pnpm add https://pkg.pr.new/vite-hub/vitehub/@vitehub/workflow@main

export default defineNuxtConfig({
  modules: ['@vitehub/workflow/nuxt'],
})

import { defineWorkflow, readValidatedPayload } from '@vitehub/workflow'

export default defineWorkflow(async (input?: { title?: string }) => {
  const { title } = await readValidatedPayload(input, value => ({
    title: typeof value?.title === 'string' && value.title.trim()
      ? value.title.trim()
      : 'Untitled draft',
  }))

  return {
    title,
    slug: title.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
  }
})

import { createError, readBody } from 'h3'
import { readValidatedPayload, runWorkflow } from '@vitehub/workflow'

export default defineEventHandler(async (event) => {
  const { title } = await readValidatedPayload(await readBody(event), (input) => {
    if (!input || typeof input !== 'object' || typeof input.title !== 'string' || !input.title.trim()) {
      throw createError({
        statusCode: 400,
        statusMessage: 'Enter a title for the draft.',
      })
    }

    return {
      title: input.title.trim(),
    }
  })
  const run = await runWorkflow('publish-draft', { title })

  return {
    runId: run.id,
    status: await run.status(),
  }
})

import { getRouterParam } from 'h3'
import { getWorkflowRun } from '@vitehub/workflow'

export default defineEventHandler(async (event) => {
  const run = await getWorkflowRun(getRouterParam(event, 'id'))

  if (!run)
    return { found: false }

  return {
    found: true,
    status: await run.status(),
  }
})

Defer a workflow run

Use deferWorkflow() when you want to start durable workflow work after the current response has already been committed. It reads Nitro's current request context internally, prefers a real waitUntil() hook when one exists, and otherwise falls back to best-effort fire-and-forget dispatch.

import { deferWorkflow } from '@vitehub/workflow'

export default defineEventHandler(() => {
  deferWorkflow('publish-draft', {
    title: 'Hello from waitUntil',
  })

  return { ok: true }
})

Public API

| runWorkflow(name, payload) | Start a new workflow run and get a run handle back immediately. | | getWorkflowRun(runId) | Reattach to an existing run from a later request, task, or webhook. |

Type reference

Handler signature

The handler receives an optional input and returns the workflow result. ViteHub does not enforce a return type.

type WorkflowHandler<TInput, TResult> = (
  input?: TInput,
  context?: import('@vitehub/workflow').WorkflowExecutionContext,
) => TResult | Promise<TResult>

WorkflowExecutionContext

Handlers receive a portable execution context as the second argument.

WorkflowDefinitionOptions

WorkflowRun

runWorkflow() returns a WorkflowRun handle with:

WorkflowRunStatus

Configure provider and workflow options

Workflow has one global layer and one definition layer:

• Top-level workflow config in nuxt.config.ts or nitro.config.ts selects the provider and sets up the app-wide integration.
• createWorkflow(options?)(handler) and defineWorkflow(handler, options?) both configure one workflow definition with portable options such as timeout. ::

• Netlify ignores definition-level timeout for now and executes workflows through Async Workloads event handlers.

runWorkflow() starts a new run with input for that specific execution. getWorkflowRun() reconnects to an existing run by id. Neither one replaces top-level or definition-level configuration.

export default defineNuxtConfig({
  modules: ['@vitehub/workflow/nuxt'],
  workflow: {
    provider: 'cloudflare',
  },
})

export default defineWorkflow(async (input) => {
  return input
})