Workflow quickstart

This guide creates one welcome workflow. The route accepts a payload, starts a workflow run, and returns the normalized run metadata.

The provider is the only part that changes between Cloudflare and Vercel. The workflow definition and start call stay the same.

Set up @vitehub/workflow in this app.

- Install @vitehub/workflow
- Register hubWorkflow() for Vite or @vitehub/workflow/nitro for Nitro
- Configure workflow.provider only when the hosting provider cannot be inferred
- Define welcome as a discovered workflow
- Call runWorkflow('welcome', payload) from a route
- Return the workflow run to the caller

Docs: /docs/vite/workflow/quickstart or /docs/nitro/workflow/quickstart

pnpm add @vitehub/workflow

Register the Nitro module. Cloudflare and Vercel hosting are detected automatically; set workflow.provider only when you need to override the detected provider.

import { defineNitroConfig } from 'nitro/config'

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

import { defineNitroConfig } from 'nitro/config'

export default defineNitroConfig({
  modules: ['@vitehub/workflow/nitro'],
  workflow: {
    provider: 'vercel',
  },
})

Define the workflow

Create a discovered Nitro workflow file:

import { defineWorkflow } from '@vitehub/workflow'

export type WelcomePayload = {
  email: string
  marker?: string
}

export default defineWorkflow<WelcomePayload>(async ({ id, payload, provider }) => {
  return {
    id,
    provider,
    message: `Welcome ${payload.email}`,
    marker: payload.marker,
  }
})

Start from a route

Add a Nitro route that reads the request body and starts the named workflow:

import { runWorkflow } from '@vitehub/workflow'
import type { WelcomePayload } from '../workflows/welcome'

export default defineEventHandler(async (event) => {
  const payload = await readBody<WelcomePayload>(event)
  const run = await runWorkflow('welcome', payload)

  return { ok: true, payload, run }
})

Verify the response

Run or deploy the app with a configured provider, then send a request:

curl -X POST http://localhost:3000/api/welcome \
  -H 'content-type: application/json' \
  -d '{"email":"ava@example.com","marker":"docs"}'

The route returns the workflow run metadata:

{
  "ok": true,
  "payload": {
    "email": "ava@example.com",
    "marker": "docs"
  },
  "run": {
    "id": "wrun_lvn4hx4f_x8k2p9s1",
    "provider": "vercel",
    "status": "queued"
  }
}

::