@workflow/world-vercel

@workflow/world-vercel

Production workflow backend for Vercel platform deployments.

Integrates with Vercel's infrastructure for storage, queuing, and authentication. Handles workflow persistence and scaling in production environments.

Used by default for deployments on Vercel. Authentication and API endpoints are configured automatically in Vercel deployments.

Connection failures

Backend connection failures and interrupted event streams follow existing retry policies, including failures with unrecognized error codes. Repeated HTTP/2 session failures rebuild the shared events connection pool. Invalid backend URL protocols, embedded credentials, Fetch-blocked ports, and unsupported request headers fail immediately. Interrupted event writes retain their existing in-process retries; caller cancellations are excluded.

See Backend connection failures for retry behavior and diagnostics.

Events channel

With WORKFLOW_EVENTS_TRANSPORT=ws (opt-in; the default is HTTP), or for the workflows listed in WORKFLOW_EVENTS_TRANSPORT_WS_OVERRIDE_WORKFLOWS, event writes go over a per-run WebSocket only while that run's channel is open. The queue handler opens it for each delivery, so workflows need nothing extra. Code that writes a run's events outside a delivery (a custom driver, a long-lived process) opens and releases it itself; otherwise those writes go over HTTP:

import { createWorld, openEventsChannel } from '@workflow/world-vercel';

const world = createWorld();
const release = openEventsChannel(runId);
try {
  await world.events.create(runId, event);
} finally {
  release?.();
}

It returns undefined, and writes stay on HTTP, when the transport is disabled or the World cannot hold a socket (a projectConfig World, as the CLI uses).

Custom dispatcher

HTTP requests (including the queue) default to a shared undici RetryAgent that handles connection pooling and retries. Pass a custom dispatcher to override it, for example, to tune undici on newer Node.js runtimes:

import { Agent } from 'undici';
import { createWorld } from '@workflow/world-vercel';
import { setWorld } from '@workflow/core/runtime';

setWorld(createWorld({ dispatcher: new Agent({ connections: 16 }) }));

Caller user agent

Pass a User-Agent header to append a caller-specific product token while preserving the world-vercel token:

import { createWorld } from '@workflow/world-vercel';

const world = createWorld({
  headers: { 'User-Agent': 'my-framework/1.2.3' },
});