wrangler local development supports Workflows in ctx.exports

Introduced 2026-09-27 · score 0.97

HOW TO USE IT

When a Worker declares a Workflow in `exports`, create it locally with `ctx.exports.<ClassName>.create({ params })`; use `wrangler workflows` with `--local` to trigger or inspect its instances. In Vitest, introspect through a test-only Workflow binding, which also captures instances created via `ctx.exports`.

const instance = await ctx.exports.MyWorkflow.create({ params: { name: "World" } });

npx wrangler workflows trigger <WORKFLOW_NAME> '{"name":"World"}' --local
npx wrangler workflows instances describe <WORKFLOW_NAME> <INSTANCE_ID> --local

cloudflareTest({ wrangler: { configPath: "./wrangler.jsonc" }, miniflare: { workflows: { MY_WORKFLOW: { name: "my-workflow", className: "MyWorkflow" } } } })

await using introspector = await introspectWorkflow(env.MY_WORKFLOW);
await exports.default.fetch("https://example.com/");
const instances = await introspector.get();

WHY THIS HELPS

Create and introspect a Workflow declared in a Worker’s `exports` while developing or testing the Worker locally.

BEFORE THIS CHANGE

Before this change, a Worker could define a Workflow through a `workflows` binding; calling an exported Workflow through `ctx.exports` was not available.

REQUIREMENTS AND LIMITATIONS

Version: 4.142.0
ctx.exports.MyWorkflow (required): Use the Workflow class name as the key to reach the exported Workflow API.
params: Object passed as the Workflow instance input; example uses `{ name: "World" }`.
<WORKFLOW_NAME> (required): Workflow name used by Wrangler commands.
[PARAMS]: JSON string passed as the Workflow instance parameters.
--local: Target the Workflow in a local `wrangler dev` session.
--port: Select the local dev session port; defaults to `8787`.
MY_WORKFLOW test binding (required): Vitest introspection requires a Workflow binding; configure `name` and `className` under `miniflare.workflows`.
Prerequisite: For local exported Workflows, use Wrangler 4.142.0 or later, `@cloudflare/vite-plugin` 1.61.0 or later, or `@cloudflare/vitest-plugin` 1.3.0 or later, as appropriate.
Prerequisite: Run a `wrangler dev` session before using `wrangler workflows ... --local`.
Prerequisite: Vitest helpers from `cloudflare:test` and `cloudflare:workers` must be imported from test files running in the Workers runtime.
`ctx.exports` and `workflows` bindings with the same Workflow `name` share their instances, including instances created before the Workflow was declared in `exports`.
Two Workers can't export the same Workflow name.
A binding to an exported Workflow must refer to the Worker and class that export it.
`getPlatformProxy()` ignores Workflows declared in `exports`, since it doesn't run the Worker's code.
In the Vitest plugin, `introspectWorkflow()` and `introspectWorkflowInstance()` still need a Workflow binding.
A `workflows` binding whose `script_name` is the Worker's own name resolves to the Worker itself again.

FIRST-PARTY EVIDENCE

Check the installed version and the source before using it. Entry JSON

Report a problem with this card

Tools change faster than your agent’s training data.

Changes

wrangler local development supports Workflows in ctx.exports