@astrojs/cloudflare: `imageService: 'compile'` is a silent noop with `prerenderEnvironment: 'node'`

[kitschpatrol]

Astro Info

Astro                    v7.0.7
Node                     v26.4.0
System                   macOS (arm64)
Package Manager          pnpm
Output                   static
Adapter                  @astrojs/cloudflare
Integrations             none

If this issue only occurs in one browser, which browser is a problem?

No response

Describe the Bug

With imageService: 'compile' (or { build: 'compile', runtime: 'passthrough' }) and prerenderEnvironment: 'node', the build performs no image optimization: every generated variant is just a no-op copy of the source written under the requested format's extension — e.g. PNG bytes in a .webp file. No warning or error; the build completes normally.

The docs say compile:

Uses the configured image service 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.

Explicitly configuring sharp by setting image.service.entrypoint to "astro/assets/services/sharp" doesn't help: hasUserImageService() treats astro/assets/services/sharp as not user-configured and discards it.

Workaround: imageService: 'custom' with an explicit image.service sharp entrypoint, but this is not ideal since the sharp node path won't work with runtime images, and 'custom' is not a valid value for the imageService.build key, so there's no way to define custom imageService.runtime behavior alongside a custom image service.

What's the expected result?

I'd expect a config like this to process images using Sharp via Node at build time, and then to use 'cloudflare-binding' via Workerd at runtime.

import { defineConfig } from "astro/config";
import cloudflare from "@astrojs/cloudflare";

export default defineConfig({
  adapter: cloudflare({
    prerenderEnvironment: "node",
    imageService: {
      build: "compile",
      runtime: "cloudflare-binding",
    },
  }),
  image: {
    service: {
      entrypoint: "astro/assets/services/sharp",
    },
  },
});

(Also the difference between custom and compile feels a bit murky. (It's like compile is implicitly custom if and only if a custom image service is defined?)

Link to Minimal Reproducible Example

https://github.com/kitschpatrol/repro-astro-cloudflare-image

Participation

• I am willing to submit a pull request for this issue.

[astrobot-houston]

• Reproduced: Yes
• Exploration: Yes — View branch
• Unit Test: Yes — packages/integrations/cloudflare/test/compile-image-service.test.ts
• Priority: P3: minor bug. This affects the specific combination of imageService: 'compile' with prerenderEnvironment: 'node' in the Cloudflare adapter. A workaround exists (imageService: 'custom' with explicit sharp), and the default prerenderEnvironment: 'workerd' is unaffected.

When imageService: 'compile' is used with prerenderEnvironment: 'node', the build-time image generation pipeline uses a workerd passthrough stub instead of sharp. This happens because collectStaticImages — the method that installs sharp for build-time transforms — only runs inside the workerd prerenderer (packages/integrations/cloudflare/src/prerenderer.ts), and no equivalent path exists for prerenderEnvironment: 'node'. The result is that output images are byte-for-byte copies of the source with incorrect file extensions (e.g. PNG bytes in a .webp file), with no warning emitted.

I found a potential fix for this issue. The fix wraps the default Node prerenderer with a collectStaticImages method that installs sharp (or the user's custom service) before the image generation pipeline runs, mirroring the existing workerd prerenderer behavior. It also restores the default prerender entrypoint that gets skipped when setPrerenderer is called.

Try this fix

You can test this fix right now without waiting for a release:

pnpm add https://pkg.pr.new/@astrojs/cloudflare@2d6ddb5

If this fixes your issue, please leave a comment letting us know (e.g. "confirmed, this fixes it"). We'll then open a pull request to get this merged.

Full Triage Report

Issue Details

• Author: kitschpatrol
• URL: @astrojs/cloudflare: imageService: 'compile' is a silent noop with prerenderEnvironment: 'node' #17346
• Created: 2026-07-10

Description

With imageService: 'compile' (or { build: 'compile', runtime: 'passthrough' }) and prerenderEnvironment: 'node', the build performs no image optimization: every generated variant is just a no-op copy of the source written under the requested format's extension — e.g., PNG bytes in a .webp file. No warning or error; the build completes normally.

The user reports that explicitly configuring sharp by setting image.service.entrypoint to "astro/assets/services/sharp" doesn't help either — hasUserImageService() treats astro/assets/services/sharp as not user-configured and discards it.

Expected Behavior

With imageService: { build: 'compile', runtime: 'cloudflare-binding' } and prerenderEnvironment: 'node', images should be processed using sharp at build time for prerendered routes.

Workaround

Using imageService: 'custom' with an explicit image.service sharp entrypoint works — images are properly optimized. But this doesn't allow setting separate runtime behavior.

Environment

• Astro: 7.0.7
• @astrojs/cloudflare: 14.1.2
• Node: 26.x (issue reported on 26.4.0)
• Package Manager: pnpm

Reproduction

Cloned the reporter's reproduction repo: https://github.com/kitschpatrol/repro-astro-cloudflare-image

Running astro build with imageService: { build: 'compile' } produces:

generating optimized images
  ▶ /_astro/example.-n1UJm0e_1WlxmJ.webp (before: 12kB, after: 12kB) (+2ms) (1/1)

The output .webp file is actually a PNG file — a byte-for-byte copy of the source PNG (12948 bytes) with a .webp extension. No conversion, no resizing.

Using imageService: 'custom' with explicit sharp produces a proper WebP file (494 bytes), confirming the issue is specifically with the 'compile' path.

Root Cause (Confidence: HIGH)

The bug has two interacting causes:

1. collectStaticImages only runs for prerenderEnvironment: 'workerd'

The Cloudflare adapter's workerd prerenderer has a collectStaticImages method (packages/integrations/cloudflare/src/prerenderer.ts) that overrides globalThis.astroAsset.imageService with sharp after prerendering. This method only exists on the workerd prerenderer — when prerenderEnvironment: 'node', the default Node prerenderer is used, and it has no collectStaticImages. The image generation pipeline then falls back to the workerd passthrough stub, which returns input buffers unchanged.

2. hasUserImageService() rejects explicit sharp configuration

Even if the user explicitly configures image.service.entrypoint: 'astro/assets/services/sharp', the hasUserImageService() function (packages/integrations/cloudflare/src/utils/image-config.ts) returns false because it specifically excludes sharp from being considered "user-configured."

Verification: Bug

The behavior is an oversight from feature timing. prerenderEnvironment: 'node' was added in PR #15711 (March 2026). The compile image service was reworked in PR #17099 (July 2026), but the sharp installation logic was placed inside collectStaticImages of the workerd prerenderer only. No tests cover this combination, and no comments acknowledge the limitation.

Fix

Two changes in packages/integrations/cloudflare/src/index.ts:

1. astro:build:start hook — Added an else if (hasBuildImageService) branch for prerenderEnvironment: 'node'. Wraps the default prerenderer with a collectStaticImages method that installs sharp (or the user's custom service) before image generation runs.

2. astro:build:setup hook — Restores the default prerender entrypoint that gets skipped when setPrerenderer is called, since we're still using the default Node-based prerenderer.

Before fix: (before: 12kB, after: 12kB) — output .webp is actually PNG bytes.
After fix: (before: 12kB, after: 0kB) — output is a proper WebP file (494 bytes).

All 13 tests pass (11 existing + 2 new). The prerender-node-env tests (7 tests) also pass.

This report was made by an LLM. The analysis may be wrong, and the potential fix might not work, but is intended as a starting point for exploring the issue.

[kitschpatrol]

@astrobot-houston that's a fix

[astrobot-houston]

The fix has been verified! A pull request has been created: #17347