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.

Prompt

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

Install Workflow

pnpm add @vitehub/workflow

Cloudflare uses runtime Workflow bindings. Vercel uses generated ViteHub runtime output for the same public API.

Register the integration

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

vite.config.ts

import { defineConfig } from 'vite'
import { hubWorkflow } from '@vitehub/workflow/vite'

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

vite.config.ts

import { defineConfig } from 'vite'
import { hubWorkflow } from '@vitehub/workflow/vite'

export default defineConfig({
  plugins: [hubWorkflow()],
  workflow: {
    provider: 'vercel',
  },
})

Define the workflow

Create a discovered Vite workflow file:

src/welcome.workflow.ts

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 Vite server entry that reads the request body and starts the named workflow:

src/server.ts

import { H3, readBody } from 'h3'
import { runWorkflow } from '@vitehub/workflow'
import type { WelcomePayload } from './welcome.workflow'

const app = new H3()

app.post('/api/welcome', async (event) => {
  const payload = await readBody<WelcomePayload>(event)
  const run = await runWorkflow('welcome', payload)

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

export default app

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"
  }
}