@platformatic/workflow-fastify

A Fastify plugin that runs Vercel Workflow SDK workflows without Nitro, backed by @platformatic/world.

It mounts the workflow callback handlers produced by the standalone build and registers this app's queue handler with the workflow engine. Your app keeps full ownership of its own lifecycle (Fastify owns listen(), hooks, plugins); this plugin only adds routes and a startup hook.

How it works

1. npx workflow build --target standalone transforms your 'use workflow' / 'use step' files and emits, under .well-known/workflow/v1/ (the plugin resolves the bundle extension automatically: v5 emits .mjs, v4 emits .js):
   • flow — workflow orchestration handler (POST, a Web Request => Response)
   • step — step execution handler
   • webhook — webhook resume handler
   • manifest.json — workflow/step ids + graph
2. This plugin imports those handlers and mounts them on Fastify, adapting Fastify request/reply to the Web Request/Response they expect.
3. On boot it calls @platformatic/world's start() to register the callback endpoints with the engine. Under ICC (Intelligent Command Center, Platformatic's control plane) this is a no-op: ICC registers them for you.

The build is the only step that needs the SDK's transform. At runtime this plugin needs no bundler.

Project layout

No fixed structure — the plugin only needs the build output at <buildDir>/.well-known/workflow/v1/ (buildDir defaults to process.cwd()):

my-app/
├── server.ts                 # registers the plugin; triggers by app.workflows.<name>
├── workflows/signup.ts       # 'use workflow' / 'use step'
└── .well-known/workflow/v1/  # generated by `workflow build` (don't edit/commit)

TypeScript

Two compilations, over different files — they don't share an output dir:

• Workflows ('use workflow'/'use step') are compiled by workflow build into self-contained bundles in .well-known/workflow/v1/ (already JS — exclude this dir from your tsc, like dist).
• Your server is a normal TS file. On Node 22.18+/24 it runs as-is via type stripping (no separate compile); or compile it with tsc/your toolchain. The plugin ships compiled JS, so it adds no TS requirement.

Usage

npm i @platformatic/workflow-fastify @platformatic/world fastify workflow

import Fastify from 'fastify'
import { start } from 'workflow/api'
import workflowFastify from '@platformatic/workflow-fastify'

const app = Fastify()
// mounts .well-known/workflow/v1/* and decorates app.workflows (name -> id)
await app.register(workflowFastify)

// Trigger by id. No SDK transform is needed on this file: it starts runs by
// workflowId (from app.workflows), it does not import the workflow source.
app.post('/api/signup', async (req) => {
  const run = await start({ workflowId: app.workflows.handleSignup }, [req.body.email])
  return { runId: run.runId }
})

await app.listen({ port: Number(process.env.PORT) })

Build the workflows before starting (re-run when they change):

npx workflow build --target standalone

Options

| Option | Default | Description | |---|---|---| | buildDir | process.cwd() | Directory containing .well-known/workflow/v1 | | register | true | Register the queue handler on boot (no-op under ICC, Platformatic's control plane) |

Environment

The SDK and the world resolve from environment variables:

WORKFLOW_TARGET_WORLD=@platformatic/world
PLT_WORLD_SERVICE_URL=http://<workflow-engine>:3042
PLT_WORLD_APP_ID=<app id>                 # optional, defaults to package name
PLT_WORLD_DEPLOYMENT_VERSION=<version>    # optional; auto-detected in K8s
PORT=<port>                               # used to register the callback URL locally