feat(vite-plugin): Add containers support in vite-plugin (#9819)

* feat(vite-plugin): Add containers support in `vite dev`

Adds support for Cloudflare Containers in `vite dev`.
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.

* suggestions

Co-authored-by: emily-shen <[email protected]>

* feedback fixes

---------

Co-authored-by: emily-shen <[email protected]>

Author: CarmenPopoviciu

.changeset/wet-rockets-stare.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/vite-plugin": patch
+"@cloudflare/containers-shared": patch
+"wrangler": patch
+---
+
+feat(vite-plugin): Add containers support in `vite dev`
+
+Adds support for Cloudflare Containers in `vite dev`. 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, as will containers support in `vite preview`.

packages/containers-shared/src/build.ts

@@ -1,7 +1,7 @@
 import { spawn } from "child_process";
 import { readFileSync } from "fs";
 import path from "path";
-import { BuildArgs, ContainerDevOptions, Logger } from "./types";
+import type { BuildArgs, ContainerDevOptions, Logger } from "./types";
 
 export async function constructBuildCommand(
 	options: BuildArgs,

packages/containers-shared/src/client/core/request.ts

@@ -113,8 +113,8 @@ const getFormData = (options: ApiRequestOptions): FormData | undefined => {
 	if (options.formData) {
 		const formData = new FormData();
 
-		const process = (key: string, value: any) => {
-			if (isString(value) || isBlob(value)) {
+		const process = async (key: string, value: any) => {
+			if (isString(value)) {
 				formData.append(key, value);
 			} else {
 				formData.append(key, JSON.stringify(value));
@@ -233,7 +233,7 @@ const parseResponseSchemaV4 = <T>(
 			result = {};
 		}
 	} else {
-		result = { error: fetchResult.errors?.[0].message };
+		result = { error: fetchResult.errors?.[0]?.message };
 	}
 	return {
 		url,
@@ -263,6 +263,10 @@ export const sendRequest = async (
 	};
 
 	if (config.WITH_CREDENTIALS) {
+		// :(
+		// The vite-plugin is attempting to typecheck everything with worker types, which does not support request.credentials
+		// Also note this is always set to "omit".
+		// @ts-ignore
 		request.credentials = config.CREDENTIALS;
 	}
 

packages/containers-shared/src/images.ts

@@ -4,7 +4,7 @@ import {
 	isCloudflareRegistryLink,
 } from "./knobs";
 import { dockerLoginManagedRegistry } from "./login";
-import { ContainerDevOptions } from "./types";
+import { type ContainerDevOptions } from "./types";
 import {
 	checkExposedPorts,
 	isDockerfile,
@@ -49,18 +49,25 @@ export async function pullImage(
  * such as checking if the Docker CLI is installed, and if the container images
  * expose any ports.
  */
-export async function prepareContainerImagesForDev(
-	dockerPath: string,
-	containerOptions: ContainerDevOptions[],
-	configPath: string | undefined,
+export async function prepareContainerImagesForDev(options: {
+	dockerPath: string;
+	configPath?: string;
+	containerOptions: ContainerDevOptions[];
 	onContainerImagePreparationStart: (args: {
 		containerOptions: ContainerDevOptions;
 		abort: () => void;
-	}) => void,
+	}) => void;
 	onContainerImagePreparationEnd: (args: {
 		containerOptions: ContainerDevOptions;
-	}) => void
-) {
+	}) => void;
+}) {
+	const {
+		dockerPath,
+		configPath,
+		containerOptions,
+		onContainerImagePreparationStart,
+		onContainerImagePreparationEnd,
+	} = options;
 	let aborted = false;
 	if (process.platform === "win32") {
 		throw new Error(

packages/containers-shared/src/utils.ts

@@ -1,8 +1,10 @@
-import { execFile, spawn, StdioOptions } from "child_process";
+import { execFile, spawn } from "child_process";
+import { randomUUID } from "crypto";
 import { existsSync, statSync } from "fs";
 import path from "path";
 import { dockerImageInspect } from "./inspect";
-import { ContainerDevOptions } from "./types";
+import { type ContainerDevOptions } from "./types";
+import type { StdioOptions } from "child_process";
 
 /** helper for simple docker command call that don't require any io handling */
 export const runDockerCmd = (
@@ -127,7 +129,7 @@ export const isDockerfile = (
 	}
 	const imageParts = image.split("/");
 
-	if (!imageParts[imageParts.length - 1].includes(":")) {
+	if (!imageParts[imageParts.length - 1]?.includes(":")) {
 		throw new Error(
 			errorPrefix +
 				`If this is an image registry path, it needs to include at least a tag ':' (e.g: docker.io/httpd:1)`
@@ -146,19 +148,22 @@ export const isDockerfile = (
 
 /**
  * Kills and removes any containers which come from the given image tag
+ *
+ * Please note that this function has an almost identical counterpart
+ * in the `vite-plugin-cloudflare` package (see `removeContainersByIds`).
+ * If you make any changes to this fn, please make sure you persist those
+ * changes in `removeContainersByIds` if necessary.
  */
 export const cleanupContainers = async (
 	dockerPath: string,
 	imageTags: Set<string>
 ) => {
 	try {
 		// Find all containers (stopped and running) for each built image
-		const containerIds: string[] = [];
-		for (const imageTag of imageTags) {
-			containerIds.push(
-				...(await getContainerIdsFromImage(dockerPath, imageTag))
-			);
-		}
+		const containerIds = await getContainerIdsByImageTags(
+			dockerPath,
+			imageTags
+		);
 
 		if (containerIds.length === 0) {
 			return true;
@@ -176,7 +181,31 @@ export const cleanupContainers = async (
 	}
 };
 
-const getContainerIdsFromImage = async (
+/**
+ * See https://docs.docker.com/reference/cli/docker/container/ls/#ancestor
+ *
+ * @param dockerPath The path to the Docker executable
+ * @param imageTags A set of ancestor image tags
+ * @returns The ids of all containers that share the given image tags as ancestors.
+ */
+export async function getContainerIdsByImageTags(
+	dockerPath: string,
+	imageTags: Set<string>
+): Promise<Array<string>> {
+	const ids = new Set<string>();
+
+	for (const imageTag of imageTags) {
+		const containerIdsFromImage = await getContainerIdsFromImage(
+			dockerPath,
+			imageTag
+		);
+		containerIdsFromImage.forEach((id) => ids.add(id));
+	}
+
+	return Array.from(ids);
+}
+
+export const getContainerIdsFromImage = async (
 	dockerPath: string,
 	ancestorImage: string
 ) => {
@@ -214,3 +243,10 @@ export async function checkExposedPorts(
 		);
 	}
 }
+
+/**
+ * Generates a random container build id
+ */
+export function generateContainerBuildId() {
+	return randomUUID().slice(0, 8);
+}

packages/vite-plugin-cloudflare/package.json

@@ -54,6 +54,7 @@
 		"ws": "catalog:default"
 	},
 	"devDependencies": {
+		"@cloudflare/containers-shared": "workspace:*",
 		"@cloudflare/mock-npm-registry": "workspace:*",
 		"@cloudflare/workers-shared": "workspace:*",
 		"@cloudflare/workers-tsconfig": "workspace:*",

packages/vite-plugin-cloudflare/playground/containers/Dockerfile

@@ -0,0 +1,9 @@
+FROM node:22-alpine
+
+WORKDIR /usr/src/app
+RUN echo '{"name": "simple-node-app", "version": "1.0.0", "dependencies": {"ws": "^8.0.0"}}' > package.json
+RUN npm install
+
+COPY ./container/simple-node-app.js app.js
+EXPOSE 8080
+CMD [ "node", "app.js" ]

packages/vite-plugin-cloudflare/playground/containers/__tests__/containers.spec.ts

@@ -0,0 +1,13 @@
+import { expect, test } from "vitest";
+import { getTextResponse, isBuild, isCINonLinux } 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 () => {
+	const startResponse = await getTextResponse("/start");
+	expect(startResponse).toBe("Container create request sent...");
+
+	const statusResponse = await getTextResponse("/status");
+	expect(statusResponse).toBe("true");
+});

packages/vite-plugin-cloudflare/playground/containers/container/simple-node-app.js

@@ -0,0 +1,49 @@
+const { createServer } = require("http");
+
+const webSocketEnabled = process.env.WS_ENABLED === "true";
+
+// Create HTTP server
+const server = createServer(function (req, res) {
+	if (req.url === "/ws") {
+		// WebSocket upgrade will be handled by the WebSocket server
+		return;
+	}
+
+	res.writeHead(200, { "Content-Type": "text/plain" });
+	res.write("Hello World!");
+	res.end();
+});
+
+// Check if WebSocket functionality is enabled
+if (webSocketEnabled) {
+	const WebSocket = require("ws");
+
+	// Create WebSocket server
+	const wss = new WebSocket.Server({
+		server: server,
+		path: "/ws",
+	});
+
+	wss.on("connection", function connection(ws) {
+		console.log("WebSocket connection established");
+
+		ws.on("message", function message(data) {
+			console.log("Received:", data.toString());
+			// Echo the message back with prefix
+			ws.send("Echo: " + data.toString());
+		});
+
+		ws.on("close", function close() {
+			console.log("WebSocket connection closed");
+		});
+
+		ws.on("error", console.error);
+	});
+}
+
+server.listen(8080, function () {
+	console.log("Server listening on port 8080");
+	if (webSocketEnabled) {
+		console.log("WebSocket support enabled");
+	}
+});

packages/vite-plugin-cloudflare/playground/containers/package.json

@@ -0,0 +1,19 @@
+{
+	"name": "@playground/containers",
+	"private": true,
+	"type": "module",
+	"scripts": {
+		"build": "vite build",
+		"check:types": "tsc --build",
+		"dev": "vite dev",
+		"preview": "vite preview"
+	},
+	"devDependencies": {
+		"@cloudflare/vite-plugin": "workspace:*",
+		"@cloudflare/workers-tsconfig": "workspace:*",
+		"@cloudflare/workers-types": "^4.20250617.0",
+		"typescript": "catalog:default",
+		"vite": "catalog:vite-plugin",
+		"wrangler": "workspace:*"
+	}
+}