Add opt-in Cloudflare binding image optimization during build by Desel72 · Pull Request #16194 · withastro/astro

Desel72 · 2026-04-02T16:57:38Z

Changes

Adds an opt-in compound imageService configuration for using the Cloudflare Images binding during build-time prerendering. The default imageService: 'cloudflare-binding' shorthand keeps the existing runtime-only behavior.
Uses the Cloudflare IMAGES binding in the workerd prerender worker to transform static images, writes successful transforms to the client output, and falls back to Sharp only when a transform is not returned by the binding.

Testing

Adds coverage for the config normalization behavior so the shorthand remains runtime-only and the compound cloudflare-binding config opts into build-time transforms.
Keeps the existing Cloudflare image-service coverage for binding, compile, external, dev endpoint, and static output behavior.

Docs

Docs PR: Document Cloudflare binding build-time image optimization docs#13848

changeset-bot · 2026-04-02T16:57:46Z

🦋 Changeset detected

Latest commit: 9aae56e

The changes in this PR will be included in the next version bump.

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

alexanderniebuhr

I'm not sure if this is correct. In theory the image binding should have sharp for prerender optimization. And the binding should be available when workerd is used for prerendering.

cc @OliverSpeir @Princesseuh who might have more context to share

OliverSpeir · 2026-04-02T20:21:43Z

Cloudflare-binding intentionally does not transform images on pre-rendered routes locally during build. The intention is they go to the image endpoint at request time as well, one benefit of this is faster build times

alexanderniebuhr · 2026-04-02T20:33:30Z

It should use the cloudflare binding itself to optimize them during build time though, not sharp. So like during workerd prerendering the image endpoint should be requested, which then uses cloudflare's own binding to optimize the images.

alexanderniebuhr · 2026-04-02T21:06:45Z

@Desel72 I'm sorry, but we are still discussing if this is actually an bug or the expected behavior on Discord. So we might end up not merging this, but no decision yet.

Desel72 · 2026-04-02T21:34:00Z

Thank you for the context, @alexanderniebuhr! I think I misunderstood the design intent behind cloudflare-binding. If the decision is that build-time optimization should happen for prerendered routes, I think the correct approach would be to have the workerd prerender worker call the image transform endpoint (which uses the IMAGES binding) during the build phase, rather than falling back to Sharp on the Node side. Happy to rework the approach if it turns out to be a bug that needs fixing. I think this should be fixed.

alexanderniebuhr · 2026-04-04T15:51:05Z

If the decision is that build-time optimization should happen for prerendered routes, I think the correct approach would be to have the workerd prerender worker call the image transform endpoint

@Desel72 yeah after discussion we think this the the better way. I'll update the original issue so it makes more sense. Would you like to still work on that? If so, do you want to use this PR or should we close it and you can create a new one?

Desel72 · 2026-04-04T16:11:27Z

I'd love to use this PR @alexanderniebuhr I will solve perfectly.

Desel72 · 2026-04-06T13:44:48Z

Hi @matthewp @alexanderniebuhr I've done. Welcome to your feedback. Thanks

alexanderniebuhr · 2026-04-08T07:44:25Z

@Desel72 we are going to review the PR as soon as we have bandwidth, but please fix the failing lint check :)

Desel72 · 2026-04-08T14:39:58Z

@alexanderniebuhr Thanks for your reviewing. I've solved.

Desel72 · 2026-04-10T15:21:06Z

Hi @alexanderniebuhr is there any update on this PR?

alexanderniebuhr · 2026-04-11T16:32:43Z

We are still reviewing this. Current state is that this should be put behind a option, so users can opt-in and opt-out and the changeset can't be a patch, since it's a breaking change.

alexanderniebuhr

Please make sure that this is a major change, which means we need to update the changeset as well as have an docs PR. The behavior should also put behind a flag so users can opt-in or opt-out. I suggest using the triplet configuration suggested here: #15662

Desel72 · 2026-04-19T21:48:51Z

Please make sure that this is a major change, which means we need to update the changeset as well as have an docs PR. The behavior should also put behind a flag so users can opt-in or opt-out. I suggest using the triplet configuration suggested here: #15662

Hi @alexanderniebuhr, how are you? Sorry for the late. I've solved this. Please review this.

Desel72 · 2026-04-19T22:47:29Z

@alexanderniebuhr
For the docs PR, two options — which do you prefer?
-I open it now at withastro/docs
-I wait until the config shape is finalized here
Also let me know if the triplet should include dev too (full { build, dev, runtime } from #15662).

Desel72 · 2026-05-07T13:06:21Z

Hi @alexanderniebuhr, I addressed the requested changes from the Apr 16 review:

The behavior is now opt-in via compound config.
imageService: 'cloudflare-binding' keeps the existing runtime-only behavior.
The changeset is now a major change.
Added test coverage for the config behavior.
Updated the PR title/body to match the current behavior.
Opened the docs PR: Document Cloudflare binding build-time image optimization docs#13848

Local verification:

pnpm -C packages/integrations/cloudflare build
pnpm -C packages/integrations/cloudflare exec astro-scripts test "test/{binding-image-service,compile-image-service,external-image-service,dev-image-endpoint,static}.test.ts"
pnpm -C packages/integrations/cloudflare exec astro-scripts test "test/image-config.test.ts"

Could you please re-review when you have bandwidth?

Desel72 · 2026-05-07T13:12:07Z

@alexanderniebuhr
Could you please review my PR?
Thanks!

… in cloudflare-binding mode (withastro#16035) When using the default `cloudflare-binding` image service, prerendered pages had un-optimized images because the IMAGES binding was only used at runtime. Now during the build, `handleStaticImagesRequest` uses the IMAGES binding in workerd to transform images, and the optimized bytes are written directly to the output directory. Falls back to Sharp if the binding is unavailable.

…pt-in config Per maintainer feedback, the new behavior is now opt-in via the compound `{ build: 'cloudflare-binding', runtime: 'cloudflare-binding' }` config. The string shorthand `'cloudflare-binding'` preserves the historical runtime-only behavior and is unaffected. - Extend ImageServiceConfig type with a second compound form for `cloudflare-binding` - Add `transformAtBuild` flag returned from normalizeImageServiceConfig - Bump changeset from patch to minor since this adds a new config option

github-actions Bot added the pkg: integration Related to any renderer integration (scope) label Apr 2, 2026

Desel72 mentioned this pull request Apr 2, 2026

fix(assets): resolve Picture TDZ error when combined with content render() #16171

Merged

alexanderniebuhr reviewed Apr 2, 2026

View reviewed changes

Desel72 force-pushed the fix/issue-16035 branch from 9d75820 to 904d809 Compare April 6, 2026 13:20

darbyjack mentioned this pull request Apr 8, 2026

Failing Image Optimizations PaperMC/website#230

Closed

alexanderniebuhr requested changes Apr 16, 2026

View reviewed changes

Desel72 requested a review from alexanderniebuhr May 7, 2026 12:51

Desel72 force-pushed the fix/issue-16035 branch from 00b344d to f415455 Compare May 7, 2026 12:58

Desel72 mentioned this pull request May 7, 2026

Document Cloudflare binding build-time image optimization withastro/docs#13848

Open

Desel72 changed the title ~~fix(cloudflare): enable Sharp image optimization for default cloudflare-binding mode~~ Add opt-in Cloudflare binding image optimization during build May 7, 2026

uni and others added 4 commits May 7, 2026 15:44

fix: use for-of loop to satisfy eslint prefer-for-of rule

a053222

fix(cloudflare): address binding image config feedback

9aae56e

Desel72 force-pushed the fix/issue-16035 branch from f415455 to 9aae56e Compare May 7, 2026 13:44

Uh oh!

Conversation

Desel72 commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Changes

Testing

Docs

Uh oh!

changeset-bot Bot commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

alexanderniebuhr left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

OliverSpeir commented Apr 2, 2026

Uh oh!

alexanderniebuhr commented Apr 2, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexanderniebuhr commented Apr 2, 2026

Uh oh!

Desel72 commented Apr 2, 2026

Uh oh!

alexanderniebuhr commented Apr 4, 2026

Uh oh!

Desel72 commented Apr 4, 2026

Uh oh!

Desel72 commented Apr 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

alexanderniebuhr commented Apr 8, 2026

Uh oh!

Desel72 commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Desel72 commented Apr 10, 2026

Uh oh!

alexanderniebuhr commented Apr 11, 2026

Uh oh!

alexanderniebuhr left a comment

Choose a reason for hiding this comment

Uh oh!

Desel72 commented Apr 19, 2026

Uh oh!

Desel72 commented Apr 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Desel72 commented May 7, 2026

Uh oh!

Desel72 commented May 7, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Desel72 commented Apr 2, 2026 •

edited

Loading

changeset-bot Bot commented Apr 2, 2026 •

edited

Loading

alexanderniebuhr left a comment •

edited

Loading

alexanderniebuhr commented Apr 2, 2026 •

edited

Loading

Desel72 commented Apr 6, 2026 •

edited

Loading

Desel72 commented Apr 8, 2026 •

edited

Loading

Desel72 commented Apr 19, 2026 •

edited

Loading