Emit new Worker config for same-worker Workflows (#15856)

Author: Naapperas

.changeset/workflow-ctx-exports-local.md

@@ -0,0 +1,23 @@
+---
+"miniflare": minor
+"@cloudflare/workflows-shared": minor
+"@cloudflare/vitest-plugin": minor
+"@cloudflare/vite-plugin": minor
+"wrangler": minor
+---
+
+Support Workflows declared in `exports` on `ctx.exports` in local development
+
+A Workflow declared in a Worker's `exports` is now available on `ctx.exports` in `wrangler dev`, the Vite plugin and the Vitest plugin, with the same API as a Workflow binding:
+
+```ts
+const instance = await ctx.exports.MyWorkflow.create({
+	params: { name: "World" },
+});
+```
+
+`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, and 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.
+
+`wrangler workflows` commands run with `--local` also work with Workflows declared only in `exports`, without a `workflows` binding.
+
+In the Vitest plugin, `introspectWorkflow()` and `introspectWorkflowInstance()` still need a Workflow binding, and now explain how to add one when passed a Workflow from `ctx.exports`. Instances created through `ctx.exports` are introspected too. A `workflows` binding whose `script_name` is the Worker's own name now resolves to the Worker itself again.

fixtures/get-platform-proxy/tests/get-platform-proxy.env.test.ts

@@ -312,6 +312,20 @@ describe("getPlatformProxy - env", () => {
 					"
 				`);
 		});
+
+		it("ignores Workflows declared in `exports` and doesn't crash", async ({
+			expect,
+		}) => {
+			const { dispose } = await getPlatformProxy<Env>({
+				configPath: path.join(
+					__dirname,
+					"..",
+					"wrangler_workflow_exports.jsonc"
+				),
+			});
+			await dispose();
+			expect(warn).not.toHaveBeenCalled();
+		});
 	});
 
 	describe("with a target environment", () => {

fixtures/get-platform-proxy/wrangler_workflow_exports.jsonc

@@ -0,0 +1,10 @@
+{
+	"name": "workflow-exports-test",
+	"main": "src/index.ts",
+	// `index.ts` doesn't actually export `MyWorkflow`, but `getPlatformProxy()`
+	// discards all user code anyway, so it must ignore the Workflow export.
+	"compatibility_date": "2026-08-28",
+	"exports": {
+		"MyWorkflow": { "type": "workflow", "name": "my-workflow" },
+	},
+}

fixtures/vitest-plugin-examples/package.json

@@ -30,7 +30,8 @@
 		"typegen:web-assembly": "wrangler types ./web-assembly/src/env.d.ts -c ./web-assembly/wrangler.jsonc --no-include-runtime",
 		"typegen:workers-assets": "wrangler types ./workers-assets/src/env.d.ts -c ./workers-assets/wrangler.jsonc --no-include-runtime",
 		"typegen:workers-assets-no-dir": "wrangler types ./workers-assets-no-dir/src/env.d.ts -c ./workers-assets-no-dir/wrangler.jsonc --no-include-runtime",
-		"typegen:workflows": "wrangler types ./workflows/src/env.d.ts -c ./workflows/wrangler.jsonc --no-include-runtime"
+		"typegen:workflows": "wrangler types ./workflows/src/env.d.ts -c ./workflows/wrangler.jsonc --no-include-runtime",
+		"typegen:workflows-exports": "wrangler types ./workflows-exports/src/env.d.ts -c ./workflows-exports/wrangler.jsonc --no-include-runtime"
 	},
 	"devDependencies": {
 		"@better-auth/stripe": "^1.4.6",

fixtures/vitest-plugin-examples/workflows-exports/README.md

@@ -0,0 +1,9 @@
+# 🔁 workflows-exports
+
+This Worker declares a `GreetingWorkflow` in the `exports` field of `wrangler.jsonc` instead of the `workflows` array. It has no binding, so the Worker reaches it through `ctx.exports.GreetingWorkflow`.
+
+`introspectWorkflow()` needs a Workflow binding, so the Vitest config adds a test-only binding to the same Workflow. Instances created through `ctx.exports` are introspected too.
+
+| Test                                    | Overview                                                                                 |
+| --------------------------------------- | ---------------------------------------------------------------------------------------- |
+| [exports.test.ts](test/exports.test.ts) | Runs the Workflow through `ctx.exports`, and introspects it through a test-only binding. |

fixtures/vitest-plugin-examples/workflows-exports/src/env.d.ts

@@ -0,0 +1,10 @@
+/* eslint-disable */
+// Generated by Wrangler by running `wrangler types --config=./workflows-exports/wrangler.jsonc --include-runtime=false ./workflows-exports/src/env.d.ts` (hash: 0c8cd5ae12176ebab8337cbfef98b516)
+interface __BaseEnv_Env {}
+declare namespace Cloudflare {
+	interface GlobalProps {
+		mainModule: typeof import("./index");
+	}
+	interface Env extends __BaseEnv_Env {}
+}
+interface Env extends __BaseEnv_Env {}

fixtures/vitest-plugin-examples/workflows-exports/src/index.ts

@@ -0,0 +1,29 @@
+import {
+	WorkflowEntrypoint,
+	WorkflowEvent,
+	WorkflowStep,
+} from "cloudflare:workers";
+
+type Params = { name: string };
+
+export class GreetingWorkflow extends WorkflowEntrypoint<Env, Params> {
+	async run(event: Readonly<WorkflowEvent<Params>>, step: WorkflowStep) {
+		return await step.do("greet", async () => `Hello, ${event.payload.name}!`);
+	}
+}
+
+export default {
+	async fetch(request, _env, ctx) {
+		const url = new URL(request.url);
+		const id = url.searchParams.get("id");
+		if (id !== null) {
+			const instance = await ctx.exports.GreetingWorkflow.get(id);
+			return Response.json(await instance.status());
+		}
+
+		const instance = await ctx.exports.GreetingWorkflow.create({
+			params: { name: url.searchParams.get("name") ?? "World" },
+		});
+		return Response.json({ id: instance.id });
+	},
+} satisfies ExportedHandler<Env>;

fixtures/vitest-plugin-examples/workflows-exports/src/tsconfig.json

@@ -0,0 +1,4 @@
+{
+	"extends": "../../tsconfig.workerd.json",
+	"include": ["./**/*.ts"]
+}

fixtures/vitest-plugin-examples/workflows-exports/test/env.d.ts

@@ -0,0 +1,5 @@
+declare namespace Cloudflare {
+	interface Env {
+		GREETING_WORKFLOW: Workflow; // Defined in `vitest.config.ts`
+	}
+}

fixtures/vitest-plugin-examples/workflows-exports/test/exports.test.ts

@@ -0,0 +1,51 @@
+import {
+	introspectWorkflow,
+	introspectWorkflowInstance,
+} from "cloudflare:test";
+import { env, exports } from "cloudflare:workers";
+import { it } from "vitest";
+
+it("runs a Workflow declared in `exports` through `ctx.exports`", async ({
+	expect,
+}) => {
+	const response = await exports.default.fetch(
+		"https://example.com/?name=Workers"
+	);
+	const { id } = await response.json<{ id: string }>();
+
+	await expect
+		.poll(async () => {
+			const response = await exports.default.fetch(
+				`https://example.com/?id=${id}`
+			);
+			return response.json();
+		})
+		.toMatchObject({ status: "complete", output: "Hello, Workers!" });
+});
+
+it("introspects instances created through `ctx.exports` with a binding", async ({
+	expect,
+}) => {
+	await using introspector = await introspectWorkflow(env.GREETING_WORKFLOW);
+	await introspector.modifyAll(async (m) => {
+		await m.mockStepResult({ name: "greet" }, "Hello, mock!");
+	});
+
+	await exports.default.fetch("https://example.com/");
+
+	const instances = await introspector.get();
+	expect(instances).toHaveLength(1);
+	await instances[0].waitForStatus("complete");
+	expect(await instances[0].getOutput()).toBe("Hello, mock!");
+});
+
+it("rejects introspecting a Workflow on `ctx.exports`", async ({ expect }) => {
+	await expect(introspectWorkflow(exports.GreetingWorkflow)).rejects.toThrow(
+		"`introspectWorkflow()` needs a Workflow binding from `env`"
+	);
+	await expect(
+		introspectWorkflowInstance(exports.GreetingWorkflow, "an-id")
+	).rejects.toThrow(
+		"`introspectWorkflowInstance()` needs a Workflow binding from `env`"
+	);
+});