feat(vite-plugin): Add Containers support in vite preview (#10040)

CarmenPopoviciu · web-flow · commit 26ffa055cedc · 2025-07-24T16:06:40.000+02:00
* feat(vite-plugin): Add Containers support in `vite preview`

* feedback fixes

* rebase fixes
diff --git a/.changeset/short-planes-beam.md b/.changeset/short-planes-beam.md
@@ -0,0 +1,7 @@
+---
+"@cloudflare/vite-plugin": patch
+---
+
+feat(vite-plugin): Add containers support in `vite preview`
+
+Adds support for Cloudflare Containers in `vite preview`. Please note that at the time of this PR a container image can only specify the path to a `Dockerfile`. Support for registry links will be added in a later version.
diff --git a/packages/vite-plugin-cloudflare/playground/containers/__tests__/containers.spec.ts b/packages/vite-plugin-cloudflare/playground/containers/__tests__/containers.spec.ts
@@ -1,13 +1,26 @@
-import { expect, test } from "vitest";
-import { getTextResponse, isBuild, isCINonLinux } from "../../__test-utils__";
+import { expect, test, vi } from "vitest";
+import {
+	getTextResponse,
+	isCINonLinux,
+	viteTestUrl,
+} from "../../__test-utils__";
 
-// skip build test until containers support is implemented in `vite preview`
 // We can only really run these tests on Linux, because we build our images for linux/amd64,
 // and github runners don't really support container virtualization in any sane way
-test.skipIf(isBuild || isCINonLinux)("starts container", async () => {
+test.skipIf(isCINonLinux)("starts container", async () => {
 	const startResponse = await getTextResponse("/start");
 	expect(startResponse).toBe("Container create request sent...");
 
 	const statusResponse = await getTextResponse("/status");
 	expect(statusResponse).toBe("true");
+
+	await vi.waitFor(
+		async () => {
+			const fetchResponse = await fetch(`${viteTestUrl}/fetch`, {
+				signal: AbortSignal.timeout(500),
+			});
+			expect(await fetchResponse.text()).toBe("Hello World!");
+		},
+		{ timeout: 2000, interval: 500 }
+	);
 });
diff --git a/packages/vite-plugin-cloudflare/src/containers.ts b/packages/vite-plugin-cloudflare/src/containers.ts
@@ -1,4 +1,12 @@
-import { runDockerCmd } from "@cloudflare/containers-shared/src/utils";
+import assert from "node:assert";
+import path from "node:path";
+import { prepareContainerImagesForDev } from "@cloudflare/containers-shared/src/images";
+import { getDevContainerImageName } from "@cloudflare/containers-shared/src/knobs";
+import {
+	isDockerfile,
+	runDockerCmd,
+} from "@cloudflare/containers-shared/src/utils";
+import type { WorkerConfig } from "./plugin-config";
 
 /**
  * Returns the path to the Docker executable as defined by the
@@ -45,3 +53,108 @@ export async function removeContainersByIds(
 		return;
 	}
 }
+
+/**
+ * @returns Container options suitable for building or pulling images,
+ * with image tag set to well-known dev format, or undefined if
+ * containers are not enabled or not configured.
+ */
+async function getContainerOptions(options: {
+	containersConfig: WorkerConfig["containers"];
+	isContainersEnabled: boolean;
+	containerBuildId: string;
+	configPath?: string;
+}) {
+	const {
+		containersConfig,
+		isContainersEnabled,
+		containerBuildId,
+		configPath,
+	} = options;
+
+	if (!containersConfig?.length || isContainersEnabled === false) {
+		return undefined;
+	}
+
+	return containersConfig.map((container) => {
+		if (isDockerfile(container.image, configPath)) {
+			return {
+				dockerfile: container.image,
+				image_build_context:
+					container.image_build_context ?? path.dirname(container.image),
+				image_vars: container.image_vars,
+				class_name: container.class_name,
+				image_tag: getDevContainerImageName(
+					container.class_name,
+					containerBuildId
+				),
+			};
+		} else {
+			return {
+				image_uri: container.image,
+				class_name: container.class_name,
+				image_tag: getDevContainerImageName(
+					container.class_name,
+					containerBuildId
+				),
+			};
+		}
+	});
+}
+
+/**
+ * Builds or pulls the container images for local development, and returns the
+ * corresponding list of image tags
+ *
+ * @param options.containersConfig The configured containers
+ * @param options.containerBuildId The container build id
+ * @param options.isContainersEnabled Whether containers is enabled for this Worker
+ * @param options.dockerPath The path to the Docker executable
+ * @param options.configPath The path of the wrangler configuration file
+ * @returns The list of image tags corresponding to the built/pulled container images
+ */
+export async function prepareContainerImages(options: {
+	containersConfig: WorkerConfig["containers"];
+	containerBuildId?: string;
+	isContainersEnabled: boolean;
+	dockerPath: string;
+	configPath?: string;
+}): Promise<Set<string>> {
+	assert(
+		options.containerBuildId,
+		"Build ID should be set if containers are enabled and defined"
+	);
+
+	const {
+		containersConfig,
+		isContainersEnabled,
+		dockerPath,
+		containerBuildId,
+		configPath,
+	} = options;
+	const uniqueImageTags = new Set<string>();
+
+	// Assemble container options and build if necessary
+	const containerOptions = await getContainerOptions({
+		containersConfig,
+		containerBuildId,
+		isContainersEnabled,
+		configPath,
+	});
+
+	if (containerOptions) {
+		// keep track of them so we can clean up later
+		for (const container of containerOptions) {
+			uniqueImageTags.add(container.image_tag);
+		}
+
+		await prepareContainerImagesForDev({
+			dockerPath,
+			containerOptions,
+			onContainerImagePreparationStart: () => {},
+			onContainerImagePreparationEnd: () => {},
+		});
+	}
+
+	return uniqueImageTags;
+}
diff --git a/packages/vite-plugin-cloudflare/src/index.ts b/packages/vite-plugin-cloudflare/src/index.ts
@@ -1,12 +1,9 @@
 import assert from "node:assert";
 import * as fsp from "node:fs/promises";
 import * as path from "node:path";
-import { prepareContainerImagesForDev } from "@cloudflare/containers-shared/src/images";
-import { getDevContainerImageName } from "@cloudflare/containers-shared/src/knobs";
 import {
 	generateContainerBuildId,
 	getContainerIdsByImageTags,
-	isDockerfile,
 } from "@cloudflare/containers-shared/src/utils";
 import { generateStaticRoutingRuleMatcher } from "@cloudflare/workers-shared/asset-worker/src/utils/rules-engine";
 import replace from "@rollup/plugin-replace";
@@ -29,7 +26,11 @@ import {
 	kRequestType,
 	ROUTER_WORKER_NAME,
 } from "./constants";
-import { getDockerPath, removeContainersByIds } from "./containers";
+import {
+	getDockerPath,
+	prepareContainerImages,
+	removeContainersByIds,
+} from "./containers";
 import {
 	addDebugToVitePrintUrls,
 	getDebugPathHtml,
@@ -75,7 +76,6 @@ import type {
 	ResolvedPluginConfig,
 	WorkerConfig,
 } from "./plugin-config";
-import type { ContainerDevOptions } from "@cloudflare/containers-shared";
 import type { StaticRouting } from "@cloudflare/workers-shared/utils/types";
 import type { Unstable_RawConfig } from "wrangler";
 
@@ -99,7 +99,7 @@ export function cloudflare(pluginConfig: PluginConfig = {}): vite.Plugin[] {
 
 	const additionalModulePaths = new Set<string>();
 	const nodeJsCompatWarningsMap = new Map<WorkerConfig, NodeJsCompatWarnings>();
-	const containerImageTagsSeen = new Set<string>();
+	let containerImageTagsSeen: Set<string> | undefined;
 	let runningContainerIds: Array<string>;
 
 	return [
@@ -445,38 +445,25 @@ if (import.meta.hot) {
 					}
 
 					if (hasDevContainers) {
-						assert(
-							containerBuildId,
-							"Build ID should be set if containers are enabled and defined"
-						);
-						// Assemble container options and build if necessary
-						const containerOptions = getContainerOptions(
-							entryWorkerConfig,
-							containerBuildId
-						);
 						const dockerPath = getDockerPath();
 
-						if (containerOptions) {
-							// keep track of them so we can clean up later
-							for (const container of containerOptions) {
-								containerImageTagsSeen.add(container.image_tag);
-							}
-
-							await prepareContainerImagesForDev({
-								dockerPath,
-								containerOptions,
-								onContainerImagePreparationStart: () => {},
-								onContainerImagePreparationEnd: () => {},
-							});
-						}
+						containerImageTagsSeen = await prepareContainerImages({
+							containersConfig: entryWorkerConfig.containers,
+							containerBuildId,
+							isContainersEnabled: entryWorkerConfig.dev.enable_containers,
+							dockerPath,
+							configPath: entryWorkerConfig.configPath,
+						});
 
 						// poll Docker every two seconds and update the list of ids of all
 						// running containers
 						const dockerPollIntervalId = setInterval(async () => {
-							runningContainerIds = await getContainerIdsByImageTags(
-								dockerPath,
-								containerImageTagsSeen
-							);
+							if (containerImageTagsSeen?.size) {
+								runningContainerIds = await getContainerIdsByImageTags(
+									dockerPath,
+									containerImageTagsSeen
+								);
+							}
 						}, 2000);
 
 						/*
@@ -563,14 +550,52 @@ if (import.meta.hot) {
 					vitePreviewServer
 				);
 
+				// first Worker in the Array is always the entry Worker
+				const entryWorkerConfig = resolvedPluginConfig.workers[0];
+				const hasDevContainers =
+					entryWorkerConfig?.containers?.length &&
+					entryWorkerConfig.dev.enable_containers;
+				let containerBuildId: string | undefined;
+
+				if (hasDevContainers) {
+					containerBuildId = generateContainerBuildId();
+				}
+
 				miniflare = new Miniflare(
-					await getPreviewMiniflareOptions(
+					await getPreviewMiniflareOptions({
 						resolvedPluginConfig,
 						vitePreviewServer,
-						inputInspectorPort
-					)
+						inspectorPort: inputInspectorPort,
+						containerBuildId,
+					})
 				);
 
+				if (hasDevContainers) {
+					const dockerPath = getDockerPath();
+
+					containerImageTagsSeen = await prepareContainerImages({
+						containersConfig: entryWorkerConfig.containers,
+						containerBuildId,
+						isContainersEnabled: entryWorkerConfig.dev.enable_containers,
+						dockerPath,
+						configPath: entryWorkerConfig.configPath,
+					});
+
+					const dockerPollIntervalId = setInterval(async () => {
+						if (containerImageTagsSeen?.size) {
+							runningContainerIds = await getContainerIdsByImageTags(
+								dockerPath,
+								containerImageTagsSeen
+							);
+						}
+					}, 2000);
+
+					process.on("exit", () => {
+						clearInterval(dockerPollIntervalId);
+						removeContainersByIds(dockerPath, runningContainerIds);
+					});
+				}
+
 				handleWebSocket(vitePreviewServer.httpServer, () => {
 					assert(miniflare, `Miniflare not defined`);
 
@@ -587,7 +612,10 @@ if (import.meta.hot) {
 				);
 			},
 			async buildEnd() {
-				if (resolvedViteConfig.command === "serve") {
+				if (
+					resolvedViteConfig.command === "serve" &&
+					containerImageTagsSeen?.size
+				) {
 					const dockerPath = getDockerPath();
 					runningContainerIds = await getContainerIdsByImageTags(
 						dockerPath,
@@ -1037,42 +1065,4 @@ if (import.meta.hot) {
 			? resolvedPluginConfig.workers[environmentName]
 			: undefined;
 	}
-
-	/**
-	 * @returns Container options suitable for building or pulling images,
-	 * with image tag set to well-known dev format, or undefined if
-	 * containers are not enabled or not configured.
-	 */
-	function getContainerOptions(
-		config: WorkerConfig,
-		containerBuildId: string
-	): ContainerDevOptions[] | undefined {
-		if (!config.containers?.length || config.dev.enable_containers === false) {
-			return undefined;
-		}
-		return config.containers.map((container) => {
-			if (isDockerfile(container.image, config.configPath)) {
-				return {
-					dockerfile: container.image,
-					image_build_context:
-						container.image_build_context ?? path.dirname(container.image),
-					image_vars: container.image_vars,
-					class_name: container.class_name,
-					image_tag: getDevContainerImageName(
-						container.class_name,
-						containerBuildId
-					),
-				};
-			} else {
-				return {
-					image_uri: container.image,
-					class_name: container.class_name,
-					image_tag: getDevContainerImageName(
-						container.class_name,
-						containerBuildId
-					),
-				};
-			}
-		});
-	}
 }
diff --git a/packages/vite-plugin-cloudflare/src/miniflare-options.ts b/packages/vite-plugin-cloudflare/src/miniflare-options.ts
@@ -660,11 +660,18 @@ function getPreviewModules(
 	} satisfies Pick<WorkerOptions, "rootPath" | "modules">;
 }
 
-export async function getPreviewMiniflareOptions(
-	resolvedPluginConfig: PreviewResolvedConfig,
-	vitePreviewServer: vite.PreviewServer,
-	inspectorPort: number | false
-): Promise<MiniflareOptions> {
+export async function getPreviewMiniflareOptions(config: {
+	resolvedPluginConfig: PreviewResolvedConfig;
+	vitePreviewServer: vite.PreviewServer;
+	inspectorPort: number | false;
+	containerBuildId?: string;
+}): Promise<MiniflareOptions> {
+	const {
+		resolvedPluginConfig,
+		vitePreviewServer,
+		inspectorPort,
+		containerBuildId,
+	} = config;
 	const resolvedViteConfig = vitePreviewServer.config;
 	const workers: Array<WorkerOptions> = (
 		await Promise.all(
@@ -702,6 +709,7 @@ export async function getPreviewMiniflareOptions(
 							remoteProxySessionData?.session?.remoteProxyConnectionString,
 						remoteBindingsEnabled:
 							resolvedPluginConfig.experimental.remoteBindings,
+						containerBuildId,
 					}
 				);
 
