add containers build to build output

Author: emily-shen

.changeset/build-output-containers.md

@@ -0,0 +1,9 @@
+---
+"@cloudflare/containers-shared": patch
+"@cloudflare/vite-plugin": minor
+"wrangler": minor
+---
+
+Build Containers when emitting experimental Build Output
+
+Wrangler and the Cloudflare Vite plugin now build Dockerfile-backed Container images when experimental Build Output is enabled. Container configs are emitted under `.cloudflare/output/v0/containers` with local image references, while existing registry references pass through unchanged.

packages/containers-shared/index.ts

@@ -1,6 +1,7 @@
 export * from "./src/client";
 export { request } from "./src/client/core/request";
 export * from "./src/build";
+export * from "./src/build-output";
 export * from "./src/context";
 export * from "./src/deploy";
 export * from "./src/diff";

packages/containers-shared/package.json

@@ -33,7 +33,9 @@
 		"type:tests": "tsc -p ./tests/tsconfig.json"
 	},
 	"dependencies": {
+		"@cloudflare/build-output-utils": "workspace:*",
 		"@cloudflare/cli-shared-helpers": "workspace:*",
+		"@cloudflare/config": "workspace:*",
 		"@cloudflare/workers-utils": "workspace:*"
 	},
 	"devDependencies": {

packages/containers-shared/src/build-output.ts

@@ -0,0 +1,188 @@
+import crypto from "node:crypto";
+import path from "node:path";
+import {
+	getContainersDir,
+	writeContainerConfig,
+} from "@cloudflare/build-output-utils";
+import { removeDir } from "@cloudflare/workers-utils";
+import { UserError } from "@cloudflare/workers-utils/errors";
+import { cleanupBuiltImages, startContainerBuild } from "./build";
+import { verifyDockerInstalled } from "./utils";
+import type { BuiltImage } from "./build";
+import type { WriteContainerConfigOptions } from "@cloudflare/build-output-utils";
+import type {
+	ParsedConfigExports,
+	ParsedInputContainerConfig,
+	ParsedOutputContainerConfig,
+} from "@cloudflare/config";
+
+/**
+ * Builds and writes the Container portion of the Build Output Specification.
+ *
+ * Registry references pass through unchanged. Locally built tags are retained
+ * on success so a later deploy can resolve each emitted `localReference`.
+ *
+ * @param options - The validated config exports and Docker build environment.
+ */
+export async function buildAndWriteContainerOutput(options: {
+	config: ParsedConfigExports;
+	root: string;
+	pathToDocker: string;
+}): Promise<void> {
+	const containers = Object.entries(options.config).filter(
+		(entry): entry is [string, ParsedInputContainerConfig] =>
+			entry[1]?.type === "container"
+	);
+	const dockerfileCount = countDockerfiles(containers);
+	if (dockerfileCount > 0) {
+		await verifyDockerInstalled({
+			dockerPath: options.pathToDocker,
+			operation: "building the project",
+			imageNoun:
+				dockerfileCount === 1
+					? "the configured image"
+					: "the configured images",
+		});
+	}
+
+	const builtImages: BuiltImage[] = [];
+	let outputConfigs: WriteContainerConfigOptions[];
+	try {
+		outputConfigs = [];
+		for (const [directoryName, config] of containers) {
+			outputConfigs.push({
+				root: options.root,
+				directoryName,
+				config: await buildContainerConfig(
+					config,
+					options.root,
+					options.pathToDocker,
+					builtImages
+				),
+			});
+		}
+	} catch (error) {
+		await cleanupBuiltImages(builtImages, options.pathToDocker);
+		throwBuildError(error);
+	}
+
+	try {
+		for (const outputConfig of outputConfigs) {
+			await writeContainerConfig(outputConfig);
+		}
+	} catch (error) {
+		await Promise.all([
+			removeDir(getContainersDir(options.root)),
+			cleanupBuiltImages(builtImages, options.pathToDocker),
+		]);
+		throw error;
+	}
+}
+
+async function buildContainerConfig(
+	config: ParsedInputContainerConfig,
+	root: string,
+	pathToDocker: string,
+	builtImages: BuiltImage[]
+): Promise<ParsedOutputContainerConfig> {
+	if (config.schedulingPolicy === "durable-object") {
+		const images: NonNullable<
+			Extract<
+				ParsedOutputContainerConfig,
+				{ schedulingPolicy: "durable-object" }
+			>["images"]
+		> = {};
+		for (const [imageName, image] of Object.entries(config.images ?? {})) {
+			images[imageName] = await buildContainerImage(
+				image,
+				sanitizeRepositoryName(`${config.name}-${imageName}`),
+				root,
+				pathToDocker,
+				builtImages
+			);
+		}
+		return {
+			...config,
+			images: config.images === undefined ? undefined : images,
+		};
+	}
+
+	return {
+		...config,
+		image: await buildContainerImage(
+			config.image,
+			sanitizeRepositoryName(config.name),
+			root,
+			pathToDocker,
+			builtImages
+		),
+	};
+}
+
+async function buildContainerImage(
+	image: Extract<ParsedInputContainerConfig, { image: unknown }>["image"],
+	repositoryName: string,
+	root: string,
+	pathToDocker: string,
+	builtImages: BuiltImage[]
+): Promise<Extract<ParsedOutputContainerConfig, { image: unknown }>["image"]> {
+	if ("reference" in image) {
+		return { reference: image.reference };
+	}
+
+	const pathToDockerfile = path.resolve(root, image.dockerfile);
+	const localTag = `${repositoryName}:wrangler-${crypto.randomUUID()}`;
+	const build = await startContainerBuild({
+		build: {
+			tag: localTag,
+			pathToDockerfile,
+			buildContext:
+				image.buildContext === undefined
+					? path.dirname(pathToDockerfile)
+					: path.resolve(root, image.buildContext),
+			args: image.buildVars,
+			platform: "linux/amd64",
+		},
+		pathToDocker,
+		verifyDockerIsRunning: false,
+	});
+	await build.ready;
+
+	builtImages.push({ localTag });
+	return { localReference: localTag };
+}
+
+function countDockerfiles(
+	containers: [string, ParsedInputContainerConfig][]
+): number {
+	let count = 0;
+	for (const [, config] of containers) {
+		if (config.schedulingPolicy === "durable-object") {
+			count += Object.values(config.images ?? {}).filter(
+				(image) => "dockerfile" in image
+			).length;
+		} else if ("dockerfile" in config.image) {
+			count++;
+		}
+	}
+	return count;
+}
+
+function sanitizeRepositoryName(value: string): string {
+	return value
+		.toLowerCase()
+		.replace(/[^a-z0-9._-]+/g, "-")
+		.replace(/^-+|-+$/g, "");
+}
+
+function throwBuildError(error: unknown): never {
+	if (error instanceof Error) {
+		throw new UserError(error.message, {
+			cause: error,
+			telemetryMessage: "container build image operation failed",
+		});
+	}
+	throw new UserError("An unknown error occurred", {
+		telemetryMessage: "container build unknown error",
+	});
+}

packages/containers-shared/src/build.ts

@@ -513,59 +513,6 @@ async function checkImagePlatform(
 	}
 }
 
-/**
- * Builds a Docker image and optionally pushes it to the Cloudflare managed
- * registry.
- *
- * @param args - Build arguments including tag, Dockerfile path, build context, and platform.
- * @param pathToDocker - Path to the Docker CLI executable.
- * @param push - Whether to push the built image to the remote registry.
- * @param containerConfig - Optional container configuration for limit validation.
- * @param verifyDockerIsRunning - Whether to verify Docker before building.
- * @param complianceConfig - Compliance configuration used to select the managed registry.
- * @returns An {@link ImageRef} describing the built or pushed image.
- */
-export async function buildAndMaybePush(
-	args: BuildArgs,
-	pathToDocker: string,
-	push: boolean,
-	containerConfig?: DockerfileContainerConfig,
-	verifyDockerIsRunning?: boolean,
-	complianceConfig?: ComplianceConfig
-): Promise<ImageRef> {
-	try {
-		const build = await startContainerBuild({
-			pathToDocker,
-			verifyDockerIsRunning,
-			build: args,
-		});
-		await build.ready;
-
-		if (!push) {
-			return { newTag: args.tag };
-		}
-
-		return await pushImageIfChanged({
-			pathToDocker,
-			sourceTag: args.tag,
-			targetTag: args.tag,
-			containerConfig,
-			complianceConfig,
-			cleanupSourceTag: true,
-		});
-	} catch (error) {
-		if (error instanceof Error) {
-			throw new UserError(error.message, {
-				cause: error,
-				telemetryMessage: "container build image operation failed",
-			});
-		}
-		throw new UserError("An unknown error occurred", {
-			telemetryMessage: "container build unknown error",
-		});
-	}
-}
-
 async function buildContainerImage(
 	containerConfig: DockerfileContainerConfig,
 	pathToDocker: string,