Add opt-in Cloudflare binding image optimization during build

.changeset/fix-cloudflare-binding-image-optimization.md

@@ -0,0 +1,17 @@
+---
+'@astrojs/cloudflare': minor
+---
+
+Adds opt-in build-time image optimization for the `cloudflare-binding` image service. When enabled, the Cloudflare IMAGES binding transforms static images in the workerd prerender environment, and the optimized bytes are written directly to the output directory (falling back to the Node-side image service, e.g. Sharp, if the binding fails).
+
+To opt in, use the compound configuration form:
+
+```js
+export default defineConfig({
+  adapter: cloudflare({
+    imageService: { build: 'cloudflare-binding', runtime: 'cloudflare-binding' },
+  }),
+});
+```
+
+The string shorthand `imageService: 'cloudflare-binding'` preserves the current runtime-only behavior and is unaffected.

packages/integrations/cloudflare/src/index.ts

@@ -142,9 +142,13 @@ export default function createIntegration({
 	let hasUserBuildImageService = false;
 	let compileImageConfig: CompileImageConfig | null = null;
 
-	const { buildService, runtimeService } = normalizeImageServiceConfig(imageService);
+	const { buildService, runtimeService, transformAtBuild } =
+		normalizeImageServiceConfig(imageService);
 	const needsImagesBinding = runtimeService === 'cloudflare-binding';
 	const hasBuildImageService = buildService === 'compile' || buildService === 'custom';
+	// Opt-in: user explicitly requested build-time image transformation via the compound config.
+	// The string shorthand `'cloudflare-binding'` keeps the historical runtime-only behavior.
+	const isBindingBuild = transformAtBuild && buildService === 'cloudflare-binding';
 
 	return {
 		name: '@astrojs/cloudflare',
@@ -183,10 +187,10 @@ export default function createIntegration({
 
 				const needsSessionKVBinding = usesCloudflareKVSessionDriver(session);
 
-				// In dev, `compile` needs the IMAGES binding for real transforms
-				// (the image-transform-endpoint uses it). At build time,
+				// In dev, `compile` and binding builds need the IMAGES binding for real
+				// transforms (the image-transform-endpoint uses it). At build time,
 				// `compile` uses Sharp on the Node side instead.
-				const needsImagesBindingForDev = isCompile && command === 'dev';
+				const needsImagesBindingForDev = (isCompile || isBindingBuild) && command === 'dev';
 				const usesContentCollections = hasContentCollectionsConfig(config.srcDir);
 				const prebundleContentRuntime = command === 'dev' && usesContentCollections;
 				const isTypeGenPhase = command === 'build' || command === 'sync';
@@ -212,7 +216,9 @@ export default function createIntegration({
 										...(queues?.producers?.length && {
 											queues: { producers: queues.producers },
 										}),
-										...(needsImagesBinding &&
+										// `isBindingBuild` needs the IMAGES binding in the prerender
+										// worker even when the runtime service is `passthrough`.
+										...((needsImagesBinding || isBindingBuild) &&
 											!restWorkerConfig.images && {
 												images: { binding: imagesBindingName },
 											}),
@@ -409,7 +415,7 @@ export default function createIntegration({
 								// cannot be resolved yet. The plugin serializes this object lazily
 								// at load time, after the mutation below has happened.
 								compileImageConfig:
-									hasBuildImageService && command !== 'dev'
+									(hasBuildImageService || isBindingBuild) && command !== 'dev'
 										? (compileImageConfig = {
 												base: config.base,
 												assetsPrefix:
@@ -418,6 +424,7 @@ export default function createIntegration({
 														: undefined,
 												imageServiceEntrypoint: '@astrojs/cloudflare/image-service-workerd',
 												buildAssets: config.build.assets ?? '_astro',
+												transformWithBinding: isBindingBuild,
 											})
 										: null,
 								cacheProviderEnabled: needsWorkerCache,
@@ -497,7 +504,7 @@ export default function createIntegration({
 				// these variables at build time.
 				loadWranglerEnv(config.root, cloudflareOptions.configPath, logger);
 			},
-			'astro:build:start': ({ setPrerenderer }) => {
+			'astro:build:start': ({ setPrerenderer, logger }) => {
 				if (prerenderEnvironment === 'workerd') {
 					setPrerenderer(
 						createCloudflarePrerenderer({
@@ -508,9 +515,11 @@ export default function createIntegration({
 							trailingSlash: _config.trailingSlash,
 							cfPluginConfig,
 							hasBuildImageService,
+							hasBindingImageService: isBindingBuild,
 							userImageServiceEntrypoint: hasUserBuildImageService
 								? resolveImageServiceEntrypoint(_config.image.service.entrypoint, _config.root)
 								: undefined,
+							logger,
 						}),
 					);
 				}