fix(cloudflare): preserve user-defined image service across all image… by greatjourney589 · Pull Request #16654 · withastro/astro

greatjourney589 · 2026-05-07T21:08:14Z

Changes

Fixes #16201 — the Cloudflare adapter silently replaced a user-defined image.service with @astrojs/cloudflare/image-service-workerd whenever imageService was unset (default 'cloudflare-binding') or set to 'compile'/'cloudflare-binding'/'cloudflare'/'passthrough'. Custom services (e.g., a third-party CDN service) are now preserved across all modes.
Added a guard at the top of setImageConfig that detects a non-default image.service (entrypoint ≠ astro/assets/services/sharp) and returns the config untouched, mirroring the precedent in the existing fallback default: branch and the explicit 'custom' mode.
Emits a single logger.info line when this preservation kicks in, telling the user the override was skipped and pointing them at imageService: 'custom' to silence the notice.
Added a .changeset (@astrojs/cloudflare patch).

Testing

New unit test: packages/integrations/cloudflare/test/image-config.test.ts (10 cases) covering preservation across undefined, 'passthrough', 'cloudflare', 'cloudflare-binding', 'compile', and the compound { build: 'compile' } / { build: 'compile', runtime: 'cloudflare-binding' } configs. Also asserts the existing override of default sharp in 'cloudflare-binding' and 'compile' is preserved (no regression) and that explicit 'custom' continues to work.
Existing image-related fixture tests run clean: external-image-service.test.ts (2/2), binding-image-service.test.ts (7/7), compile-image-service.test.ts (5/5).
pnpm run build succeeds; tsc -b clean.

Docs

No user-facing docs changes needed. Behavior aligns with what the existing docs already imply (a custom image.service should be respected); this PR brings the Cloudflare adapter into line. Worth a brief note in the Cloudflare adapter README that custom services are preserved alongside imageService modes — happy to follow up in withastro/docs if maintainers prefer.

Closes #16201

…Service modes

changeset-bot · 2026-05-07T21:08:21Z

🦋 Changeset detected

Latest commit: 5f6d386

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

… image service is set

greatjourney589 · 2026-05-07T22:20:20Z

Thanks for tackling this! I want to flag that this PR fixes one of the two bugs identified in the issue, but I think the second one still needs to be addressed before the issue can be closed.

The issue describes two distinct bugs

From #16201:

In setImageConfig() (image-config.js), the "compile" case unconditionally overrides the image service…

Additionally, in prerenderer.js, collectStaticImages hardcodes astro/assets/services/sharp for build-time image transforms…

The first controls which service handles getURL() / getHTMLAttributes(); the second controls which service performs the actual byte-level transform during SSG.

What this PR fixes

The early-return guard in setImageConfig correctly preserves a user-defined image.service across all imageService modes. After this PR, a custom service's getURL() and getHTMLAttributes() will be called as expected. ✅

What this PR does not fix

packages/integrations/cloudflare/src/prerenderer.ts still contains:
const { default: sharpService } = await import('astro/assets/services/sharp');
globalThis.astroAsset ??= {};
globalThis.astroAsset.imageService = sharpService;
This unconditionally installs sharp as the build-time transform service, regardless of what the user configured in image.service. So even after this PR, a custom service wired up for an external CDN/transform pipeline:

✅ will be used for URL generation and HTML attributes

❌ will not be used for the actual image transforms during build: "compile" — sharp still runs

For users whose custom service exists specifically to route transforms through an external pipeline (e.g., an image CDN's on-the-fly resize endpoint), this means they still need a workaround — currently I'm using a Vite plugin that traps the globalThis.astroAsset.imageService assignment with Object.defineProperty to prevent the sharp override.

Suggestion

Could the same hasCustomService check be applied in collectStaticImages to skip the sharp default when the user has configured a custom service? Something like:
const hasCustomService =
  config.image.service.entrypoint !== 'astro/assets/services/sharp';

if (!hasCustomService) {
  const { default: sharpService } = await import('astro/assets/services/sharp');
  globalThis.astroAsset ??= {};
  globalThis.astroAsset.imageService = sharpService;
}
// else: leave it to the user's service to register itself, or load it via its entrypoint
Happy to test against my reproduction repo if you'd like to extend the PR — otherwise I can open a follow-up. Either way, thanks for moving this forward!

Hi, @adamchal ,
I've just updated, please review again.
Thanks.

adamchal · 2026-05-07T22:52:24Z

@greatjourney589 confirmed this works very well. This is really smart sleuthing and great work! Thanks again for taking the time on this.

ematipico

The changeset needs to be reworded. I added more comments regarding code and tests

ematipico · 2026-05-12T10:09:28Z

+Preserve user-defined image services when the Cloudflare adapter is used. Previously, the adapter's `imageService` mode (including the default `'cloudflare-binding'` and `'compile'`) would silently overwrite a custom `image.service` configured in `astro.config.*`, replacing it with the workerd image service. Custom services (e.g., third-party CDNs) are now preserved across all modes, matching the behavior of the explicit `'custom'` mode.
+
+Additionally, the workerd prerenderer no longer hard-swaps `globalThis.astroAsset.imageService` to `astro/assets/services/sharp` for byte-level static image generation when a custom service is in use. Previously the `'compile'` mode bypassed the preserved service during the Node-side image generation pass; it now uses the user's configured service throughout the build.


This changeset is too lenghtly and too focused on the technical side of the fix. Changesets are meant for end users, not maintainers. Follow this guide https://contribute.docs.astro.build/docs-for-code-changes/changesets/#tips-and-examples

ematipico · 2026-05-12T10:12:15Z

+	// effect or `'compile'`/`'cloudflare-binding'` is selected.
+	const hasCustomService = config.service.entrypoint !== 'astro/assets/services/sharp';
+	if (hasCustomService && buildService !== 'custom') {
+		logger.info(


We already check for custom in the switch, we just need to add hasCustomService check there and fallback to sharp otherwise.

ematipico · 2026-05-12T10:16:26Z

+function createNoopLogger(): AstroIntegrationLogger {
+	const noop = () => {};
+	const logger = {
+		options: {} as never,
+		label: 'test',
+		fork: () => logger,
+		info: noop,
+		warn: noop,
+		error: noop,
+		debug: noop,
+	};
+	return logger as unknown as AstroIntegrationLogger;
+}


This isn't needed, you can reduce this stub to

const spyLogger = new SpyLogger(); const logger = spyLogger.forkIntegrationLogger('test-spy');

this is what we use in the mdx tests

ematipico · 2026-05-12T10:17:37Z

+	for (const mode of [
+		undefined, // default → 'cloudflare-binding'
+		'passthrough',
+		'cloudflare',
+		'cloudflare-binding',
+		'compile',
+		{ build: 'compile' as const },
+		{ build: 'compile' as const, runtime: 'cloudflare-binding' as const },
+	]) {


Shouldn't we test custom too? That's essentially where the PR is fixing things

delucis · 2026-06-12T17:10:40Z

Hey @greatjourney589 are you still interested in working on this or should we close this PR?

adamchal · 2026-06-15T20:31:38Z

@greatjourney589 I’m happy to take this over and see it through if you are strapped. It’s a real sore spot on my projects.

adamchal · 2026-06-16T20:14:57Z

I submitted a separate PR #17099 that directly addresses the issue #16201. This PR should be updated to:

Undo 5f6d386
Remove the reference to [Bug]: imageService: { build: "compile" } overrides user-configured custom image service #16201 in the PR body as this does not really address it.
Re-focus on the original PR’s intent: user-defined image.service survives undefined Cloudflare adapter imageService instead of explicitly requiring it to be set to custom

delucis · 2026-06-17T14:43:17Z

Thanks @adamchal. Ok in that case I'll close this one.

fix(cloudflare): preserve user-defined image service across all image…

8ee1917

…Service modes

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

This comment was marked as low quality.

Sign in to view

fix(cloudflare): skip sharp swap in workerd prerenderer when a custom…

5f6d386

… image service is set

ematipico requested changes May 12, 2026

View reviewed changes

delucis closed this Jun 17, 2026

		Preserve user-defined image services when the Cloudflare adapter is used. Previously, the adapter's `imageService` mode (including the default `'cloudflare-binding'` and `'compile'`) would silently overwrite a custom `image.service` configured in `astro.config.*`, replacing it with the workerd image service. Custom services (e.g., third-party CDNs) are now preserved across all modes, matching the behavior of the explicit `'custom'` mode.

		Additionally, the workerd prerenderer no longer hard-swaps `globalThis.astroAsset.imageService` to `astro/assets/services/sharp` for byte-level static image generation when a custom service is in use. Previously the `'compile'` mode bypassed the preserved service during the Node-side image generation pass; it now uses the user's configured service throughout the build.

Uh oh!

Uh oh!

Conversation

greatjourney589 commented May 7, 2026

Changes

Testing

Docs

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

This comment was marked as low quality.

greatjourney589 commented May 7, 2026

The issue describes two distinct bugs

What this PR fixes

What this PR does not fix

Suggestion

Uh oh!

adamchal commented May 7, 2026

Uh oh!

ematipico left a comment

Choose a reason for hiding this comment

Uh oh!

ematipico May 12, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico May 12, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico May 12, 2026

Choose a reason for hiding this comment

Uh oh!

ematipico May 12, 2026

Choose a reason for hiding this comment

Uh oh!

delucis commented Jun 12, 2026

Uh oh!

adamchal commented Jun 15, 2026

Uh oh!

adamchal commented Jun 16, 2026

Uh oh!

delucis commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot Bot commented May 7, 2026 •

edited

Loading