Update Cloudflare imageService docs for custom image service support

[adamchal]

Clarify that compile mode uses a configured custom image.service when defined (running its getURL()/getHTMLAttributes() hooks during prerendering), and that custom mode now also generates optimized assets at build time via the service's transform() hook, without bundling Sharp when it is not needed.

See withastro/astro#17099.

Description (required)

Two mode descriptions were out of date:

• compile previously always used the adapter's internal workerd image service. It now uses the configured image.service if one is defined (running its custom getURL() and getHTMLAttributes() hooks while prerendering), and falls back to the internal dependencies only when no custom service is set.
• custom previously ran only at runtime. It now also generates optimized image assets at build time for prerendered routes (the service's transform() hook runs at build), and Sharp is no longer bundled into the worker when the configured service does not need it.

The edits keep the existing bullet structure, reuse the existing Image Options link, and preserve the existing workerd runtime caveat on custom.

Related issues & labels (optional)

• Related: Respect custom image services for Cloudflare build-time generation (compile + custom) astro#17099
• Suggested label: improve or update documentation

Discord username: adam.chal

[astrobot-houston]

Lunaria Status Overview

🌕 This pull request will trigger status changes.

Learn more

By default, every PR changing files present in the Lunaria configuration's files property will be considered and trigger status changes accordingly.

You can change this by adding one of the keywords present in the ignoreKeywords property in your Lunaria configuration file in the PR's title (ignoring all files) or by including a tracker directive in the merged commit's description.

Tracked Files

File	Note
en/guides/integrations-guide/cloudflare.mdx	Source changed, localizations will be marked as outdated.

Warnings reference

Icon	Description
🔄️	The source for this localization has been updated since the creation of this pull request, make sure all changes in the source have been applied.

[astrobot-houston]

Hello! Thank you for opening your first PR to Astro’s Docs! 🎉

Here’s what will happen next:

1. Our GitHub bots will run to check your changes.
   If they spot any broken links you will see some error messages on this PR.
   Don’t hesitate to ask any questions if you’re not sure what these mean!

2. In a few minutes, you’ll be able to see a preview of your changes on Netlify 🥳.

3. One or more of our maintainers will take a look and may ask you to make changes.
   We try to be responsive, but don’t worry if this takes a few days.

[github-actions]

Preview deployment

✅ Deployment complete!

• Latest commit: 4c191c9
• Preview: https://docs-cloudflare-custom-image-service.previews.docs.astro.build
• Workflow run: View logs

[ArmandPhilippot]

Thank you, and welcome. Sorry for the delay, with v7 release, I didn't have the chance to review this sooner!

I don't know if this is because I'm not familiar enough with Cloudflare but the lengthy explanations from the two PRs confused me a bit. I hope I got it right. 😄 Feel free to double check the accuracy of my suggestions!

What bothers me currently is that some elements look like implementation details (so, not helpful for the user), and it isn't really clear what falls under pre-rendering versus on-demand rendering.

[ArmandPhilippot]

Does mentioning "getURL() and getHTMLAttributes() hooks" important to the user? I'm not familiar with Cloudflare, but this sounds like an implementation detail to me.

It's also not clear to me if the behavior has changed for on-demand rendering. I would say no IIUC, but then the suggested description might be a bit confusing.

Maybe the following is enough:

Suggested change

- **`compile`:** Uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options) if one is defined, running its custom `getURL()` and `getHTMLAttributes()` hooks while prerendering. Otherwise, it 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.

- **`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.

[ArmandPhilippot]

Same here "where its transform() hook runs at build time" sounds like an implementation detail to me and the user doesn't need to know that?
And I'm not sure "Sharp is not bundled into the worker when the configured service does not require it." is the right wording.

Maybe something like:

Suggested change

- **`custom`:** Always uses the image service configured in [Image Options](/en/reference/configuration-reference/#image-options), both for runtime image handling and for build-time asset generation for prerendered routes, where its `transform()` hook runs at build time. Sharp is not bundled into the worker when the configured service does not require it. **This option will not check to see whether the configured image service works in Cloudflare's `workerd` runtime.**

- **`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.

If you think adding "Sharp is not compatible." at this end is helpful, I don't mind! But, I think it makes more sense to point out that Sharp is the default and that's why it could be bundled rather than your wording.