workflow 5.0.0-beta.5 → 5.0.0-beta.51

package/docs/deploying/index.mdx

@@ -1,95 +0,0 @@
----
-title: Deploying
-icon: Rocket
-description: Deploy workflows locally, on Vercel, or anywhere using pluggable World adapters.
-type: overview
-summary: Learn how to deploy workflows to different environments using World adapters.
-related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
-  - /docs/deploying/building-a-world
----
-
-Workflows are designed to be highly portable. The same workflow code can run locally during development, on Vercel with zero configuration, or on any infrastructure using **Worlds** — pluggable adapters that handle storage, queuing, and communication.
-
-## Local Development
-
-During local development, workflows automatically use the **Local World** — no configuration required. The Local World stores workflow data in a `.workflow-data/` directory and processes steps synchronously, making it perfect for development and testing.
-
-```bash
-# Just run your dev server - workflows work out of the box
-npm run dev
-```
-
-You can inspect local workflow data using the CLI:
-
-```bash
-npx workflow inspect runs
-```
-
-<Callout>
-  Learn more about the [Local World](/worlds/local) configuration and internals.
-</Callout>
-
-## Deploying to Vercel
-
-The easiest way to deploy workflows to production is on Vercel. When you deploy to Vercel, workflows automatically use the **Vercel World** — again, with zero configuration.
-
-The Vercel World provides:
-
-- **Durable storage** - Workflow state persists across function invocations
-- **Managed queuing** - Steps are processed reliably with automatic retries
-- **Automatic scaling** - Workflows scale with your application
-- **Built-in observability** - View workflow runs in the Vercel dashboard
-
-Simply deploy your application:
-
-```bash
-vercel deploy
-```
-
-<FluidComputeCallout />
-
-<Callout>
-  Learn more about the [Vercel World](/worlds/vercel) and its capabilities.
-</Callout>
-
-## Self-Hosting & Other Providers
-
-For self-hosting or deploying to other cloud providers, you can use community-maintained Worlds or build your own.
-
-<Cards>
-  <Card title="Explore Worlds" href="/worlds">
-    Browse official and community World implementations with compatibility status and performance benchmarks.
-  </Card>
-  <Card title="Build Your Own" href="/docs/deploying/building-a-world">
-    Learn how to implement a custom World for your infrastructure.
-  </Card>
-</Cards>
-
-### Using a Third-Party World
-
-To use a different World implementation, set the `WORKFLOW_TARGET_WORLD` environment variable:
-
-```bash
-export WORKFLOW_TARGET_WORLD=@workflow/world-postgres
-# Plus any world-specific configuration
-export DATABASE_URL=postgres://...
-```
-
-Each World may have its own configuration requirements — refer to the specific World's documentation for details.
-
-## Observability
-
-The [Observability tools](/docs/observability) work with any World backend. By default they connect to your local environment, but can be configured to inspect remote deployments:
-
-```bash
-# Inspect local workflows
-npx workflow inspect runs
-
-# Inspect remote workflows
-npx workflow inspect runs --backend @workflow/world-postgres
-```
-
-Learn more about [Observability](/docs/observability) tools.

package/docs/deploying/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "Deploying",
-  "pages": ["...deploying", "building-a-world"]
-}

package/docs/deploying/world/local-world.mdx

@@ -1,84 +0,0 @@
----
-title: Local World
-description: Zero-config world bundled with Workflow for local development. No external services required.
-type: integration
-summary: Set up the Local World for zero-config workflow development on your machine.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/deploying/world/postgres-world
-  - /docs/deploying/world/vercel-world
----
-
-The Local World is bundled with `workflow` and used automatically during local development. No installation or configuration required.
-
-To explicitly use the local world in any environment, set the environment variable:
-
-```bash
-WORKFLOW_TARGET_WORLD=local
-```
-
-## Observability
-
-The `workflow` CLI uses the local world by default. Running these commands inside your workflow project will show your local development workflows:
-
-```bash
-# List recent workflow runs
-npx workflow inspect runs
-
-# Launch the web UI
-npx workflow web
-```
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance />
-
-## Configuration
-
-The local world works with zero configuration, but you can customize behavior through environment variables or programmatically via `createLocalWorld()`.
-
-### `WORKFLOW_LOCAL_DATA_DIR`
-
-Directory for storing workflow data as JSON files. Default: `.workflow-data/`
-
-### `PORT`
-
-The application dev server port. Used to enqueue steps and workflows. Default: auto-detected
-
-### `WORKFLOW_LOCAL_BASE_URL`
-
-Full base URL override for HTTPS or custom hostnames. Default: `http://localhost:{port}`
-
-Port resolution priority: `baseUrl` > `port` > `PORT` > auto-detected
-
-### `WORKFLOW_LOCAL_QUEUE_CONCURRENCY`
-
-Maximum number of concurrent queue workers. Default: `100`
-
-### Programmatic configuration
-
-{/* @skip-typecheck: incomplete code sample */}
-```typescript title="workflow.config.ts" lineNumbers
-import { createLocalWorld } from "@workflow/world-local";
-
-const world = createLocalWorld({
-  dataDir: "./custom-workflow-data",
-  port: 5173,
-  // baseUrl overrides port if set
-  baseUrl: "https://local.example.com:3000",
-});
-```
-
-## Limitations
-
-The local world is designed for development, not production:
-
-- **In-memory queue** - Steps are queued in memory and do not persist across server restarts
-- **Filesystem storage** - Data is stored in local JSON files
-- **Single instance** - Cannot handle distributed deployments
-- **No authentication** - Suitable only for local development
-
-For production deployments, use the [Vercel World](/worlds/vercel) or [Postgres World](/worlds/postgres).

package/docs/deploying/world/meta.json

@@ -1,4 +0,0 @@
-{
-  "title": "World",
-  "pages": ["local-world", "vercel-world", "postgres-world"]
-}

package/docs/deploying/world/postgres-world.mdx

@@ -1,224 +0,0 @@
----
-title: Postgres World
-description: Production-ready, self-hosted world using PostgreSQL for storage and graphile-worker for job processing.
-type: integration
-summary: Deploy workflows to your own infrastructure using PostgreSQL and graphile-worker.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/vercel-world
----
-
-The Postgres World is a production-ready backend for self-hosted deployments. It uses PostgreSQL for durable storage and [graphile-worker](https://github.com/graphile/worker) for reliable job processing.
-
-Use the Postgres World when you need to deploy workflows on your own infrastructure outside of Vercel - such as a Docker container, Kubernetes cluster, or any cloud that supports long-running servers.
-
-## Installation
-
-Install the Postgres World package in your workflow project:
-
-```package-install
-@workflow/world-postgres
-```
-
-Configure the required environment variables to use the world and point it to your PostgreSQL database:
-
-```bash title=".env"
-WORKFLOW_TARGET_WORLD="@workflow/world-postgres"
-WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
-```
-
-Run the migration script to create the necessary tables in your database. Ensure `WORKFLOW_POSTGRES_URL` is set when running this command:
-
-```bash
-npx workflow-postgres-setup
-```
-
-<Callout type="info">
-The migration is idempotent and can safely be run as a post-deployment lifecycle script.
-</Callout>
-
-## Starting the World
-
-To subscribe to the graphile-worker queue, your workflow app needs to start the world on server start. Here are examples for a few frameworks:
-
-<Tabs items={["Next.js", "SvelteKit", "Nitro"]}>
-
-<Tab value="Next.js">
-
-Create an `instrumentation.ts` file in your project root:
-
-```ts title="instrumentation.ts" lineNumbers
-export async function register() {
-  if (process.env.NEXT_RUNTIME !== "edge") {
-    const { getWorld } = await import("workflow/runtime");
-    const world = await getWorld();
-    await world.start?.();
-  }
-}
-```
-
-<Callout type="info">
-Learn more about [Next.js Instrumentation](https://nextjs.org/docs/app/guides/instrumentation).
-</Callout>
-
-</Tab>
-
-<Tab value="SvelteKit">
-
-Create a `src/hooks.server.ts` file:
-
-```ts title="src/hooks.server.ts" lineNumbers
-import type { ServerInit } from "@sveltejs/kit";
-
-export const init: ServerInit = async () => {
-  const { getWorld } = await import("workflow/runtime");
-  const world = await getWorld();
-  await world.start?.();
-};
-```
-
-<Callout type="info">
-Learn more about [SvelteKit Hooks](https://svelte.dev/docs/kit/hooks).
-</Callout>
-
-</Tab>
-
-<Tab value="Nitro">
-
-Create a plugin to start the world on server initialization:
-
-```ts title="plugins/start-pg-world.ts" lineNumbers
-import { defineNitroPlugin } from "nitro/~internal/runtime/plugin";
-
-export default defineNitroPlugin(async () => {
-  const { getWorld } = await import("workflow/runtime");
-  const world = await getWorld();
-  await world.start?.();
-});
-```
-
-Register the plugin in your config:
-
-```ts title="nitro.config.ts"
-import { defineNitroConfig } from "nitropack";
-
-export default defineNitroConfig({
-  modules: ["workflow/nitro"],
-  plugins: ["plugins/start-pg-world.ts"],
-});
-```
-
-<Callout type="info">
-Learn more about [Nitro Plugins](https://v3.nitro.build/docs/plugins).
-</Callout>
-
-</Tab>
-
-</Tabs>
-
-<Callout type="info">
-The Postgres World requires a long-lived worker process that polls the database for jobs. This does not work on serverless environments. For Vercel deployments, use the [Vercel World](/worlds/vercel) instead.
-</Callout>
-
-## Observability
-
-Use the `workflow` CLI to inspect workflows stored in PostgreSQL:
-
-```bash
-# Set your database URL
-export WORKFLOW_POSTGRES_URL="postgres://user:password@host:5432/database"
-
-# List workflow runs
-npx workflow inspect runs --backend @workflow/world-postgres
-
-# Launch the web UI
-npx workflow web --backend @workflow/world-postgres
-```
-
-If `WORKFLOW_POSTGRES_URL` is not set, the CLI defaults to `postgres://world:world@localhost:5432/world`.
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance />
-
-## Configuration
-
-All configuration options can be set via environment variables or programmatically via `createWorld()`.
-
-### `WORKFLOW_POSTGRES_URL` (required)
-
-PostgreSQL connection string. Falls back to `DATABASE_URL` if not set.
-
-Default: `postgres://world:world@localhost:5432/world`
-
-### `WORKFLOW_POSTGRES_JOB_PREFIX`
-
-Prefix for graphile-worker queue job names. Useful when sharing a database between multiple applications.
-
-### `WORKFLOW_POSTGRES_WORKER_CONCURRENCY`
-
-Number of concurrent workers polling for jobs. Default: `50`.
-
-This value also bounds how many parent→child workflow polls can be in flight simultaneously. Every `await childRun.returnValue` inside a workflow holds a worker slot until the child run terminates — if you expect recursive or highly-fanned-out parent/child workflows, raise this ceiling above the peak number of concurrent polls. With the default of 50, the included `fibonacciWorkflow` e2e test (fib(6), ~24 concurrent polls at peak) passes; deeper recursion or larger fanouts need a correspondingly larger setting.
-
-### `WORKFLOW_POSTGRES_MAX_POOL_SIZE`
-
-Maximum size of the internal `pg.Pool` used when `createWorld()` constructs the pool. Default: `10`
-
-For higher worker concurrency, Graphile Worker recommends setting `maxPoolSize` to `10` or `queueConcurrency + 2`, whichever is larger.
-
-### Programmatic configuration
-
-{/*@skip-typecheck: incomplete code sample*/}
-
-```typescript title="workflow.config.ts" lineNumbers
-import { createWorld } from "@workflow/world-postgres";
-
-const world = createWorld({
-  connectionString: "postgres://user:password@host:5432/database",
-  jobPrefix: "myapp_",
-  queueConcurrency: 50,
-  maxPoolSize: 52, // overrides WORKFLOW_POSTGRES_MAX_POOL_SIZE
-});
-```
-
-## How It Works
-
-The Postgres World uses PostgreSQL as a durable backend:
-
-- **Storage** - Workflow runs, events, steps, and hooks are stored in PostgreSQL tables
-- **Job Queue** - [graphile-worker](https://github.com/graphile/worker) handles reliable job processing with retries
-- **Streaming** - PostgreSQL NOTIFY/LISTEN enables real-time event distribution
-
-This architecture ensures workflows survive application restarts with all state reliably persisted. For implementation details, see the [source code](https://github.com/vercel/workflow/tree/main/packages/world-postgres).
-
-## Deployment
-
-Deploy your application to any cloud that supports long-running servers:
-
-- Docker containers
-- Kubernetes clusters
-- Virtual machines
-- Platform-as-a-Service providers (Railway, Render, Fly.io, etc.)
-
-Ensure your deployment has:
-
-1. Network access to your PostgreSQL database
-2. Environment variables configured correctly
-3. The `start()` function called on server initialization
-
-<Callout type="info">
-The Postgres World is not compatible with Vercel deployments. On Vercel, workflows automatically use the [Vercel World](/worlds/vercel) with zero configuration.
-</Callout>
-
-## Limitations
-
-- **Requires long-running process** - Must call `start()` on server initialization; not compatible with serverless platforms
-- **PostgreSQL infrastructure** - Requires a PostgreSQL database (self-hosted or managed)
-- **Not compatible with Vercel** - Use the [Vercel World](/worlds/vercel) for Vercel deployments
-
-For local development, use the [Local World](/worlds/local) which requires no external services.

package/docs/deploying/world/vercel-world.mdx

@@ -1,179 +0,0 @@
----
-title: Vercel World
-description: Fully-managed world for Vercel deployments with automatic storage, queuing, and authentication.
-type: integration
-summary: Deploy workflows to Vercel with fully-managed storage, queuing, and authentication.
-prerequisites:
-  - /docs/deploying
-related:
-  - /docs/how-it-works/encryption
-  - /docs/deploying/world/local-world
-  - /docs/deploying/world/postgres-world
----
-
-The Vercel World is a fully-managed workflow backend for applications deployed on Vercel. It provides scalable storage, distributed queuing, and automatic authentication with zero configuration.
-
-When you deploy to Vercel, workflows automatically use the Vercel World - no setup required.
-
-## Usage
-
-Deploy your application to Vercel:
-
-```bash
-vercel deploy
-```
-
-That's it. Vercel automatically:
-
-- Selects the Vercel World backend
-- Configures authentication using OIDC tokens
-- Provisions storage and queuing infrastructure
-- Isolates data per environment (production, preview, development)
-
-<FluidComputeCallout />
-
-## Vercel platform documentation
-
-For complete details on pricing, usage limits, and included allotments on Vercel, see the official Vercel documentation:
-
-- **[Vercel Workflow](https://vercel.com/docs/workflow)** — Pricing details, concepts, and observability for Workflow on Vercel
-- **[Vercel limits](https://vercel.com/docs/limits)** — Platform-wide limits including Workflow-specific constraints
-- **[Vercel Hobby plan](https://vercel.com/docs/plans/hobby)** — Free tier included usage for Workflow and other resources
-
-For self-hosted deployments, use the [Postgres World](/worlds/postgres). For local development, use the [Local World](/worlds/local).
-
-## Limitations
-
-- **Single-region deployment** - The backend infrastructure is currently deployed only in `iad1`. Applications in other regions will route workflow requests to `iad1`, which may result in higher latency. For best performance, deploy your Vercel apps using Workflow to `iad1`. Global deployment is planned to colocate the backend closer to your applications.
-
-- **Data residency** - The Vercel World is currently deployed in the `iad1` region. This means independently of the deployment location of your application, the data for your workflows will be stored in the `iad1` region.
-
-## Observability
-
-Workflow observability is built into the Vercel dashboard on your project page. It respects your existing authentication and project permission settings.
-
-The `workflow` CLI commands open a browser window deeplinked to the Vercel dashboard:
-
-```bash
-# List workflow runs (opens Vercel dashboard)
-npx workflow inspect runs --backend vercel
-
-# Launch the web UI (opens Vercel dashboard)
-npx workflow web --backend vercel
-```
-
-The CLI automatically retrieves authentication from the Vercel CLI (`vercel login`) and infers project/team IDs from your local Vercel project linking.
-
-To use the local observability UI instead of the Vercel dashboard:
-
-```bash
-npx workflow web --backend vercel --localUi
-```
-
-To override the automatic configuration:
-
-```bash
-npx workflow inspect runs \
-  --backend vercel \
-  --env production \
-  --project my-project \
-  --team my-team \
-  --authToken <your-token>
-```
-
-Learn more in the [Observability](/docs/observability) documentation.
-
-## Testing & Compatibility
-
-<WorldTestingPerformance />
-
-## Configuration
-
-The Vercel World requires no configuration when deployed to Vercel. For advanced use cases, you can override settings programmatically via `createVercelWorld()`.
-
-### `WORKFLOW_VERCEL_ENV`
-
-The Vercel environment to use. Options: `production`, `preview`, `development`. Automatically detected.
-
-### `WORKFLOW_VERCEL_AUTH_TOKEN`
-
-Authentication token for API requests. Automatically detected.
-
-### `WORKFLOW_VERCEL_PROJECT`
-
-Vercel project ID for API requests. Automatically detected.
-
-### `WORKFLOW_VERCEL_TEAM`
-
-Vercel team ID for API requests. Automatically detected.
-
-### `WORKFLOW_VERCEL_BACKEND_URL`
-
-Custom base URL for the Vercel workflow API. Automatically detected.
-
-### Programmatic configuration
-
-{/*@skip-typecheck: incomplete code sample*/}
-
-```typescript title="workflow.config.ts" lineNumbers
-import { createVercelWorld } from "@workflow/world-vercel";
-
-const world = createVercelWorld({
-  token: process.env.WORKFLOW_VERCEL_AUTH_TOKEN,
-  baseUrl: "https://api.vercel.com/v1/workflow",
-  projectConfig: {
-    projectId: "my-project",
-    teamId: "my-team",
-    environment: "production",
-  },
-});
-```
-
-## Versioning
-
-On Vercel, workflow runs are pegged to the deployment that started them. This means:
-
-- Existing workflow runs continue executing on their original deployment, even as new code is deployed
-- New workflow runs start on the latest deployment
-- Code changes won't break in-flight workflows
-
-This ensures long-running workflows complete reliably without being affected by subsequent deployments.
-
-## Security
-
-### Consumer function security
-
-Workflow handler functions on Vercel are not accessible through public endpoints. During the build step, the Workflow SDK registers each handler as only reachable by [Vercel Queue](https://vercel.com/docs/queues), by using the `experimentalTriggers` configuration in `.vc-config.json`:
-
-```json title=".vc-config.json (step handler)"
-{
-  "experimentalTriggers": [
-    {
-      "type": "queue/v2beta",
-      "topic": "__wkf_step_*",
-      "consumer": "default",
-    }
-  ]
-}
-```
-
-Practically, this means:
-
-- You don't need to add authentication or authorization logic to workflow handlers
-- Unauthorized requests can never reach the step or workflow functions
-- Only messages delivered through Vercel Queues can trigger execution
-- Handlers receive only a message ID that must be retrieved from Vercel's backend, making it impossible to craft custom payloads
-
-<Callout>
-  This configuration is managed entirely by the Workflow SDK build step. You should not need to write this yourself. If you are writing a custom integration, see [Framework Integrations — Security](/docs/how-it-works/framework-integrations#security) for more details.
-</Callout>
-
-## How It Works
-
-The Vercel World uses Vercel's infrastructure for workflow execution:
-
-- **Storage** - Workflow data is stored in Vercel's cloud with automatic replication and [end-to-end encryption](/docs/how-it-works/encryption)
-- **Queuing** - Steps are distributed across serverless functions via [Vercel Queues](https://vercel.com/docs/queues) with automatic retries and [consumer function security](#consumer-function-security)
-- **Authentication** - OIDC tokens provide secure, automatic authentication
-
-For more details, see the [Vercel Workflow documentation](https://vercel.com/docs/workflow).

package/docs/migration-guides/index.mdx

@@ -1,34 +0,0 @@
----
-title: Migration Guides
-description: Move your existing durable workflow system to the Workflow SDK with side-by-side code comparisons and a realistic migration example.
-type: overview
-summary: Migrate from Temporal, Inngest, AWS Step Functions, or trigger.dev to the Workflow SDK.
-related:
-  - /docs/foundations/workflows-and-steps
-  - /docs/getting-started
----
-
-<Callout type="info">
-Install the Workflow SDK migration skill:
-
-```bash
-npx skills add https://github.com/vercel/workflow --skill migrating-to-workflow-sdk
-```
-</Callout>
-
-Move an existing orchestration system to the Workflow SDK. Each guide pairs a concept-mapping table with side-by-side code, so you can translate one piece of your codebase at a time.
-
-<Cards>
-    <Card href="/docs/migration-guides/migrating-from-temporal" title="Migrating from Temporal">
-        Map Activities, Workers, Signals, and Child Workflows onto workflows, steps, hooks, and `start()` / `getRun()`.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-inngest" title="Migrating from Inngest">
-        Map `createFunction`, `step.run`, `step.sleep`, `step.waitForEvent`, and `step.invoke` onto workflows, steps, and hooks.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-aws-step-functions" title="Migrating from AWS Step Functions">
-        Replace ASL JSON states, Task / Choice / Wait / Parallel states, and `.waitForTaskToken` callbacks with TypeScript.
-    </Card>
-    <Card href="/docs/migration-guides/migrating-from-trigger-dev" title="Migrating from trigger.dev">
-        Map `task()`, `schemaTask()`, `wait.for` / `wait.forToken`, `triggerAndWait`, and `metadata.stream` onto workflows, steps, hooks, and `start()` / `getRun()`.
-    </Card>
-</Cards>

package/docs/migration-guides/meta.json

@@ -1,9 +0,0 @@
-{
-  "title": "Migration Guides",
-  "pages": [
-    "migrating-from-temporal",
-    "migrating-from-inngest",
-    "migrating-from-aws-step-functions",
-    "migrating-from-trigger-dev"
-  ]
-}