From 06e5f1a5d2d66c5db41e51ae5980042c69b7afba Mon Sep 17 00:00:00 2001 From: Captain Date: Thu, 7 May 2026 15:04:36 +0200 Subject: [PATCH 1/4] Document Cloudflare binding image build config --- .../en/guides/integrations-guide/cloudflare.mdx | 17 +++++++++++++++-- 1 file changed, 15 insertions(+), 2 deletions(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index e663d1a1971aa..cb5658fd7412a 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -116,7 +116,7 @@ It also accepts the following: ### `imageService`

-**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' }`
+**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' } | { build: 'cloudflare-binding', runtime?: 'cloudflare-binding' | 'passthrough' }`
**Default:** `'cloudflare-binding'`

@@ -128,7 +128,7 @@ Determines which image service is used by the adapter. The adapter will default - **`compile`:** Uses a combination of internal dependencies to transform images locally at build time for prerendered routes. The noop `passthrough` option is configured for on-demand rendered pages. - **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options). **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.** -It is also possible to configure your image service as an object, setting both a build time and runtime service independently. Currently, `'compile'` is the only available build-time option. The supported runtime options are `'passthrough'` (default) and `'cloudflare-binding'`: +It is also possible to configure your image service as an object, setting both a build time and runtime service independently. The supported build-time options are `'compile'` and `'cloudflare-binding'`. The supported runtime options are `'passthrough'` (default) and `'cloudflare-binding'`: ```js title="astro.config.mjs" ins={6} import { defineConfig } from 'astro/config'; @@ -141,6 +141,19 @@ export default defineConfig({ }); ``` +To opt in to build-time image optimization with the Cloudflare Images binding during `workerd` prerendering, set `build` to `'cloudflare-binding'`. The default string shorthand, `imageService: 'cloudflare-binding'`, keeps the existing runtime-only behavior. + +```js title="astro.config.mjs" ins={6} +import { defineConfig } from 'astro/config'; +import cloudflare from '@astrojs/cloudflare'; + +export default defineConfig({ + adapter: cloudflare({ + imageService: { build: 'cloudflare-binding', runtime: 'cloudflare-binding' } + }), +}); +``` + ### `sessionKVBindingName`

From 651a5eb9c2b133b5a2afaafa215276e36b1f2609 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:43:57 +0200 Subject: [PATCH 2/4] Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx Co-authored-by: Armand Philippot --- .../docs/en/guides/integrations-guide/cloudflare.mdx | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 20c070583a120..98e34c962cf39 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -128,7 +128,11 @@ Determines which image service is used by the adapter. The adapter will default - **`compile`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) or falls back to a combination of internal dependencies to transform images locally at build time for prerendered routes. The noop `passthrough` option is configured for on-demand rendered pages. - **`custom`:** Uses the [configured image service](/en/reference/configuration-reference/#imageservice) (defaults to Sharp) to process assets at build time for prerendered routes. Bundles the image service for runtime image handling, without checking its compatibility with Cloudflare's `workerd` runtime. -It is also possible to configure your image service as an object, setting both a build time and runtime service independently. The supported build-time options are `'compile'` and `'cloudflare-binding'`. The supported runtime options are `'passthrough'` (default) and `'cloudflare-binding'`: +

+ +You can also configure the image service as an object by providing a build-time service (`compile` or `cloudflare-binding`) and, optionally, a runtime service (`passthrough` or `cloudflare-binding`). + +When the runtime service is omitted, its default value depends on the configured build-time service. It falls back to `'passthrough'` for `build: 'compile'` and to `'cloudflare-binding'` for `build: 'cloudflare-binding'`. ```js title="astro.config.mjs" ins={6} import { defineConfig } from 'astro/config'; From de5a5e8c543504903edf3fb12f70b96677844c86 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Thu, 30 Jul 2026 09:44:14 +0200 Subject: [PATCH 3/4] Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/integrations-guide/cloudflare.mdx | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index 98e34c962cf39..d29c15634ee23 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -145,7 +145,9 @@ export default defineConfig({ }); ``` -To opt in to build-time image optimization with the Cloudflare Images binding during `workerd` prerendering, set `build` to `'cloudflare-binding'`. The default string shorthand, `imageService: 'cloudflare-binding'`, keeps the existing runtime-only behavior. +Using `imageService: 'cloudflare-binding'` enables image optimization using the [Cloudflare Images binding](https://developers.cloudflare.com/images/transform-images/bindings/) only at runtime. + +To opt in to build-time image optimization with the binding during `workerd` prerendering, set `build` to `'cloudflare-binding'`. If the binding fails to transform an image at build time, the adapter falls back to the [configured image service](/en/reference/configuration-reference/#imageservice) (defaults to Sharp). ```js title="astro.config.mjs" ins={6} import { defineConfig } from 'astro/config'; From 357c6370009453e0871e90cf2cf7a004cf51f662 Mon Sep 17 00:00:00 2001 From: Alexander Niebuhr <45965090+alexanderniebuhr@users.noreply.github.com> Date: Thu, 30 Jul 2026 14:50:17 +0200 Subject: [PATCH 4/4] Update src/content/docs/en/guides/integrations-guide/cloudflare.mdx Co-authored-by: Armand Philippot --- src/content/docs/en/guides/integrations-guide/cloudflare.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx index d29c15634ee23..a865dea00154f 100644 --- a/src/content/docs/en/guides/integrations-guide/cloudflare.mdx +++ b/src/content/docs/en/guides/integrations-guide/cloudflare.mdx @@ -116,7 +116,7 @@ It also accepts the following: ### `imageService`

-**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile', runtime?: 'cloudflare-binding' | 'passthrough' } | { build: 'cloudflare-binding', runtime?: 'cloudflare-binding' | 'passthrough' }`
+**Type:** `'passthrough' | 'cloudflare' | 'cloudflare-binding' | 'compile' | 'custom' | { build: 'compile' | 'cloudflare-binding', runtime?: 'cloudflare-binding' | 'passthrough' }`
**Default:** `'cloudflare-binding'`