@platformatic/world

Drop-in World implementation for Vercel Workflow DevKit on self-hosted Kubernetes. Routes workflow state through a central Workflow Service that pins each run to the deployment version that started it.

Installation

npm install @platformatic/world

Usage

With the Vercel Workflow SDK

Set two environment variables and the SDK discovers the world automatically:

WORKFLOW_TARGET_WORLD=@platformatic/world
PLT_WORLD_SERVICE_URL=http://localhost:3042

Your app needs to call world.start() once on server startup to register a queue handler. In Next.js, use instrumentation.ts:

// instrumentation.ts
export async function register() {
  if (process.env.PLT_WORLD_SERVICE_URL) {
    const { createWorld } = await import('@platformatic/world')
    const world = createWorld()
    await world.start?.()
  }
}

For other frameworks, call world.start() during your server's startup.

In Kubernetes with ICC, handler registration is automatic — world.start() is a no-op.

Direct usage

import { createWorld } from '@platformatic/world'

const world = createWorld({
  serviceUrl: 'http://localhost:3042',
  appId: 'my-app',
  deploymentVersion: 'v1',
})

// world implements the full World interface:
// storage (runs, events, steps, hooks), queue, streams, encryption

Configuration

createWorld(options?)

High-level factory with automatic config resolution from environment variables.

| Option | Env var | Default | Description | |---|---|---|---| | serviceUrl | PLT_WORLD_SERVICE_URL | required | Workflow Service URL | | appId | PLT_WORLD_APP_ID | package.json name | Application identifier | | deploymentVersion | PLT_WORLD_DEPLOYMENT_VERSION | K8s label or 'local' | Deployment version |

In Kubernetes, the deployment version is auto-detected from the pod's plt.dev/version label via the K8s API.

createPlatformaticWorld(config)

Low-level factory — all fields required, no env var resolution.

import { createPlatformaticWorld } from '@platformatic/world'

const world = createPlatformaticWorld({
  serviceUrl: 'http://localhost:3042',
  appId: 'my-app',
  deploymentVersion: 'v1',
})

Spec version support

@platformatic/world declares specVersion: SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT (3). In practice:

• Runs created by start() are tagged with spec v3.
• Queue messages between client and server use CBOR framing. CBOR preserves Uint8Array natively (JSON does not), so binary workflow input survives the queue round-trip without base64 wrapping.
• createQueueHandler accepts both CBOR and JSON inbound via a dual transport. A v3 client can be deployed against a v2-only server during rollout; a v2 client can be deployed against a v3 server.

Peer dependency: @workflow/world ≥ 4.1.1 (the first stable release exporting SPEC_VERSION_SUPPORTS_CBOR_QUEUE_TRANSPORT).

Workflow SDK compatibility

Our World API is typed against @workflow/[email protected] stable, but the same world instance also works at runtime against @workflow/[email protected] (the unreleased v5 line).

| Installed workflow SDK | Works at runtime | Notes | |---|---|---| | [email protected] (stable) | ✅ | The declared API. Streamer calls route through the flat methods (writeToStream, getStreamChunks, ...). | | [email protected] | ✅ | The v5 SDK calls world.streams.* (nested namespace, different argument order). We expose these at runtime alongside the v4 methods. | | [email protected] (pre-CBOR) | ⚠️ | Works, but without CBOR transport. Runs stay on spec v2 (JSON queue). |

We verify both SDK versions in CI (e2e/ runs against v5 beta to mirror Vercel's community-world suite; e2e-v4/ runs against v4.2.4 stable to guard the primary user-facing path).

The v5 breaking changes (PR #1293, streamer namespace rename + runId-first argument order, required runId on steps.get) are additive from our side — we keep the v4 flat methods as the canonical interface and expose the v5 streams.* namespace as a runtime addition.

License

Apache-2.0