feat(vite-plugin): Add support for email and cron triggers (#10416)

CarmenPopoviciu · jamesopstad · web-flow · commit 7b05c8ef51ec · 2025-08-22T15:46:27.000+02:00
Add support for testing [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/#test-cron-triggers-locally) and [Email Workers](https://developers.cloudflare.com/email-routing/email-workers/local-development/) in `vite dev` and `vite preview`. * feat(vite-plugin): Add support for email triggers * feedback fixes * feat(vite-plugin): add cron triggers playground * fix tests * feedback suggestions Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com> * Update packages/vite-plugin-cloudflare/playground/cron-triggers/wrangler.jsonc Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com> * feedback fixes * feedback fixes <3 Dario * fix lock file * fix tests * fix indentation --------- Co-authored-by: James Opstad <13586373+jamesopstad@users.noreply.github.com>
diff --git a/.changeset/wide-donuts-sin.md b/.changeset/wide-donuts-sin.md
@@ -0,0 +1,5 @@
+---
+"@cloudflare/vite-plugin": minor
+---
+
+Add support for testing [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/#test-cron-triggers-locally) and [Email Workers](https://developers.cloudflare.com/email-routing/email-workers/local-development/) in `vite dev` and `vite preview`.
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/__tests__/cron-triggers.spec.ts b/packages/vite-plugin-cloudflare/playground/cron-triggers/__tests__/cron-triggers.spec.ts
@@ -0,0 +1,8 @@
+import { expect, test } from "vitest";
+import { getTextResponse, serverLogs } from "../../__test-utils__";
+
+test("Supports testing Cron Triggers at '/cdn-cgi/handler/scheduled' route", async () => {
+	const cronResponse = await getTextResponse("/cdn-cgi/handler/scheduled");
+	expect(cronResponse).toBe("ok");
+	expect(serverLogs.info.join()).toContain("Cron processed");
+});
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/package.json b/packages/vite-plugin-cloudflare/playground/cron-triggers/package.json
@@ -0,0 +1,19 @@
+{
+	"name": "@playground/cron-trigger-worker",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"check:type": "tsc --build",
+		"dev": "vite dev",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "catalog:default",
+		"typescript": "catalog:default",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "workspace:*"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/src/index.ts b/packages/vite-plugin-cloudflare/playground/cron-triggers/src/index.ts
@@ -0,0 +1,11 @@
+import { WorkerEntrypoint } from "cloudflare:workers";
+
+export default class extends WorkerEntrypoint {
+	override async fetch(): Promise<Response> {
+		return new Response("Hello cron trigger Worker playground!");
+	}
+
+	override async scheduled() {
+		console.log("Cron processed");
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.json b/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.node.json b/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.node.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/base.json"],
+	"include": ["vite.config.ts", "__tests__"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.worker.json b/packages/vite-plugin-cloudflare/playground/cron-triggers/tsconfig.worker.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
+	"include": ["src"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/turbo.json b/packages/vite-plugin-cloudflare/playground/cron-triggers/turbo.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"outputs": ["dist/**"]
+		}
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/vite.config.ts b/packages/vite-plugin-cloudflare/playground/cron-triggers/vite.config.ts
@@ -0,0 +1,6 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [cloudflare({ inspectorPort: false, persistState: false })],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/cron-triggers/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/cron-triggers/wrangler.jsonc
@@ -0,0 +1,8 @@
+{
+	"name": "cron-trigger-worker",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-02-14",
+	"triggers": {
+		"crons": ["* * * * *"], // every minute
+	},
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/__tests__/email-triggers.spec.ts b/packages/vite-plugin-cloudflare/playground/email-worker/__tests__/email-triggers.spec.ts
@@ -0,0 +1,42 @@
+import dedent from "ts-dedent";
+import { expect, test } from "vitest";
+import { getTextResponse, serverLogs, viteTestUrl } from "../../__test-utils__";
+
+test("Supports sending email via the email binding", async () => {
+	const sendEmailResponse = await getTextResponse("/send");
+	expect(sendEmailResponse).toBe("Email message sent successfully!");
+});
+
+test("Supports testing Email Workers at '/cdn-cgi/handler/scheduled' route", async () => {
+	const params = new URLSearchParams();
+	params.append("from", "sender@example.com");
+	params.append("to", "recipient@example.com");
+
+	const fetchResponse = await fetch(
+		`${viteTestUrl}/cdn-cgi/handler/email?${params}`,
+		{
+			method: "POST",
+			body: dedent`
+				From: "John" <sender@example.com>
+				Reply-To: sender@example.com
+				To: recipient@example.com
+				Subject: Testing Email Workers Local Dev
+				Content-Type: text/html; charset="windows-1252"
+				X-Mailer: Curl
+				Date: Tue, 27 Aug 2024 08:49:44 -0700
+				Message-ID: <6114391943504294873000@ZSH-GHOSTTY>
+
+				Hi there
+			`,
+		}
+	);
+
+	const emailStdout = serverLogs.info.join();
+	expect(await fetchResponse.text()).toBe(
+		"Worker successfully processed email"
+	);
+	expect(emailStdout).toContain(
+		`Received email from sender@example.com on ${new Date(" 27 Aug 2024 08:49:44 -0700").toISOString()} with following message:`
+	);
+	expect(emailStdout).toContain("Hi there");
+});
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/package.json b/packages/vite-plugin-cloudflare/playground/email-worker/package.json
@@ -0,0 +1,23 @@
+{
+	"name": "@playground/email-worker",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"check:type": "tsc --build",
+		"dev": "vite dev",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "catalog:default",
+		"@types/mimetext": "^2.0.4",
+		"mimetext": "^3.0.27",
+		"postal-mime": "2.4.4",
+		"ts-dedent": "^2.2.0",
+		"typescript": "catalog:default",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "workspace:*"
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/src/index.ts b/packages/vite-plugin-cloudflare/playground/email-worker/src/index.ts
@@ -0,0 +1,50 @@
+import { EmailMessage } from "cloudflare:email";
+import { WorkerEntrypoint } from "cloudflare:workers";
+import { createMimeMessage } from "mimetext";
+import * as PostalMime from "postal-mime";
+import type { SendEmail } from "@cloudflare/workers-types";
+
+interface Env {
+	EMAIL: SendEmail;
+}
+
+export default class extends WorkerEntrypoint<Env> {
+	override async fetch(request: Request): Promise<Response> {
+		const url = new URL(request.url);
+
+		if (url.pathname === "/send") {
+			const msg = createMimeMessage();
+			msg.setSender({ name: "Sending email test", addr: "sender@example.com" });
+			msg.setRecipient("recipient@example.com");
+			msg.setSubject("An email generated in a Worker");
+			msg.addMessage({
+				contentType: "text/plain",
+				data: `Congratulations, you just sent an email from a Worker.`,
+			});
+			const message = new EmailMessage(
+				"sender@example.com",
+				"recipient@example.com",
+				msg.asRaw()
+			);
+
+			try {
+				await this.env.EMAIL.send(message);
+			} catch (error) {
+				throw error;
+			}
+
+			return new Response("Email message sent successfully!");
+		}
+
+		return new Response("Hello Email Workers playground!");
+	}
+
+	async email(message: ForwardableEmailMessage) {
+		const parser = new PostalMime.default();
+		const rawEmail = new Response(message.raw);
+		const email = await parser.parse(await rawEmail.arrayBuffer());
+		console.log(
+			`Received email from ${email.from.address} on ${email.date} with following message:\n\n ${email.html}`
+		);
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.json b/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.json
@@ -0,0 +1,7 @@
+{
+	"files": [],
+	"references": [
+		{ "path": "./tsconfig.node.json" },
+		{ "path": "./tsconfig.worker.json" }
+	]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.node.json b/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.node.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/base.json"],
+	"include": ["vite.config.ts", "__tests__"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.worker.json b/packages/vite-plugin-cloudflare/playground/email-worker/tsconfig.worker.json
@@ -0,0 +1,4 @@
+{
+	"extends": ["@cloudflare/workers-tsconfig/worker.json"],
+	"include": ["src"]
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/turbo.json b/packages/vite-plugin-cloudflare/playground/email-worker/turbo.json
@@ -0,0 +1,9 @@
+{
+	"$schema": "http://turbo.build/schema.json",
+	"extends": ["//"],
+	"tasks": {
+		"build": {
+			"outputs": ["dist/**"]
+		}
+	}
+}
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/vite.config.ts b/packages/vite-plugin-cloudflare/playground/email-worker/vite.config.ts
@@ -0,0 +1,6 @@
+import { cloudflare } from "@cloudflare/vite-plugin";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+	plugins: [cloudflare({ inspectorPort: false, persistState: false })],
+});
diff --git a/packages/vite-plugin-cloudflare/playground/email-worker/wrangler.jsonc b/packages/vite-plugin-cloudflare/playground/email-worker/wrangler.jsonc
@@ -0,0 +1,12 @@
+{
+	"name": "email-worker",
+	"main": "src/index.ts",
+	"compatibility_date": "2025-02-14",
+	"compatibility_flags": ["nodejs_compat"],
+	"send_email": [
+		{
+			"name": "EMAIL",
+			"allowed_destination_addresses": ["recipient@example.com"],
+		},
+	],
+}
diff --git a/packages/vite-plugin-cloudflare/src/index.ts b/packages/vite-plugin-cloudflare/src/index.ts
@@ -9,7 +9,7 @@ import {
 } from "@cloudflare/containers-shared/src/utils";
 import { generateStaticRoutingRuleMatcher } from "@cloudflare/workers-shared/asset-worker/src/utils/rules-engine";
 import MagicString from "magic-string";
-import { Miniflare } from "miniflare";
+import { CoreHeaders, Miniflare } from "miniflare";
 import colors from "picocolors";
 import * as vite from "vite";
 import {
@@ -1066,6 +1066,40 @@ if (import.meta.hot) {
 				}
 			},
 		},
+		// Plugin to handle cron/email/etc triggers
+		{
+			name: "vite-plugin-cloudflare:trigger-handlers",
+			enforce: "pre",
+			async configureServer(viteDevServer) {
+				assertIsNotPreview(resolvedPluginConfig);
+
+				if (resolvedPluginConfig.type === "workers") {
+					const entryWorkerConfig = getEntryWorkerConfig(resolvedPluginConfig);
+					assert(entryWorkerConfig, `No entry Worker config`);
+
+					const entryWorkerName = entryWorkerConfig.name;
+
+					// cron && email triggers
+					viteDevServer.middlewares.use("/cdn-cgi/", (req, res, next) => {
+						const requestHandler = createRequestHandler((request) => {
+							assert(miniflare, `Miniflare not defined`);
+
+							// set the target service that handles these requests
+							// to point to the User Worker (see `getTargetService` fn in
+							// `packages/miniflare/src/workers/core/entry.worker.ts`)
+							request.headers.set(CoreHeaders.ROUTE_OVERRIDE, entryWorkerName);
+							return miniflare.dispatchFetch(request, { redirect: "manual" });
+						});
+
+						// `req.url` is the URL of the request relative to the middleware
+						// mount path. Here we ensure that miniflare receives a request that
+						// reflects the original request url
+						req.url = req.originalUrl;
+						requestHandler(req, res, next);
+					});
+				}
+			},
+		},
 	];
 
 	function getWorkerConfig(environmentName: string) {
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -533,6 +533,7 @@ export async function getDevMiniflareOptions(config: {
 		inspectorPort: inspectorPort === false ? undefined : inspectorPort,
 		unsafeInspectorProxy: inspectorPort !== false,
 		unsafeDevRegistryPath: getDefaultDevRegistryPath(),
+		unsafeTriggerHandlers: true,
 		handleRuntimeStdio(stdout, stderr) {
 			const decoder = new TextDecoder();
 			stdout.forEach((data) => logger.info(decoder.decode(data)));
@@ -780,7 +781,7 @@ export async function getPreviewMiniflareOptions(config: {
 							: { modules: true, script: "" }),
 					},
 					...externalWorkers,
-				] as Array<WorkerOptions>;
+				] satisfies Array<WorkerOptions>;
 			})
 		)
 	).flat();
@@ -792,6 +793,7 @@ export async function getPreviewMiniflareOptions(config: {
 		inspectorPort: inspectorPort === false ? undefined : inspectorPort,
 		unsafeInspectorProxy: inspectorPort !== false,
 		unsafeDevRegistryPath: getDefaultDevRegistryPath(),
+		unsafeTriggerHandlers: true,
 		handleRuntimeStdio(stdout, stderr) {
 			const decoder = new TextDecoder();
 			stdout.forEach((data) => logger.info(decoder.decode(data)));
diff --git a/pnpm-lock.yaml b/pnpm-lock.yaml

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +"@cloudflare/vite-plugin": minor
 +---
++
 +Add support for testing [Cron Triggers](https://developers.cloudflare.com/workers/configuration/cron-triggers/#test-cron-triggers-locally) and [Email Workers](https://developers.cloudflare.com/email-routing/email-workers/local-development/) in `vite dev` and `vite preview`.