IMAGES-2191: improve variant URLs returned by miniflare hosted images mock by mglewis · Pull Request #13348 · cloudflare/workers-sdk

mglewis · 2026-04-08T12:03:40Z

The miniflare hosted images mock currently returns bare variant names (e.g. "public") in the variants field of ImageMetadata. In production, this field contains full delivery URLs such as https://imagedelivery.net/<account_hash>/<image_id>/public. These bare names are not usable in an <img src=...>, resulting in variant URLs failing to display when running in local mode.

This PR introduces a local image delivery endpoint at /cdn-cgi/imagedelivery/<image_id>/<variant> that serves image bytes directly from the existing miniflare KV store. The variants field now returns absolute URLs pointing to this endpoint (<hostname>/cdn-cgi/imagedelivery/<image>/public), making them functional in a browser during local development.

Implementation Details

The approach follows the same pattern used by the Stream binding (#13234), with a reserved /cdn-cgi/ path intercepted by the entry worker and forwarded to the images service.

CorePaths.IMAGE_DELIVERY and CoreBindings.SERVICE_IMAGES_DELIVERY have been added as entry worker constants.
The entry worker routes /cdn-cgi/imagedelivery/ requests to the images service
The images service fetch() handler serves raw bytes from KV using sharp.js for content type detection (via /info in the binding)
The images service name is passed from the miniflare config assembler to the global services builder, which conditionally binds it to the entry worker
Variant URLs are resolved to absolute URLs at read time via the /core/public-url loopback route introduced in [Stream] Add support for serving videos locally + watermark/caption upload support #13234, so they always reflect the current Miniflare publicUrl (tolerating restarts). This boilerplate previously lived in a stream specific nook of the codebase, but has been relocated to a helper in miniflare:shared.

Testing

Three new tests added for the delivery endpoint:

Variant URLs use the correct /cdn-cgi/imagedelivery/ format
Delivery endpoint serves uploaded image bytes
Delivery endpoint returns 404 for non-existent images

Running my local test worker, the images now load:

Tests

Tests included/updated
Automated tests not possible - manual testing has been completed as follows:
Additional testing not necessary because:
Public documentation
- Cloudflare docs PR(s):
- Documentation not necessary because: this feature hasn't been released yet

changeset-bot · 2026-04-08T12:03:46Z

🦋 Changeset detected

Latest commit: 4a1f61c

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

pkg-pr-new · 2026-04-08T12:10:56Z

create-cloudflare

npm i https://pkg.pr.new/create-cloudflare@13348

@cloudflare/kv-asset-handler

npm i https://pkg.pr.new/@cloudflare/kv-asset-handler@13348

miniflare

npm i https://pkg.pr.new/miniflare@13348

@cloudflare/pages-shared

npm i https://pkg.pr.new/@cloudflare/pages-shared@13348

@cloudflare/unenv-preset

npm i https://pkg.pr.new/@cloudflare/unenv-preset@13348

@cloudflare/vite-plugin

npm i https://pkg.pr.new/@cloudflare/vite-plugin@13348

@cloudflare/vitest-pool-workers

npm i https://pkg.pr.new/@cloudflare/vitest-pool-workers@13348

@cloudflare/workers-editor-shared

npm i https://pkg.pr.new/@cloudflare/workers-editor-shared@13348

@cloudflare/workers-utils

npm i https://pkg.pr.new/@cloudflare/workers-utils@13348

wrangler

npm i https://pkg.pr.new/wrangler@13348

commit: 7e305cb

workers-devprod · 2026-04-08T12:21:27Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

packages/miniflare/src/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/plugins/core/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/core/constants.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/core/entry.worker.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/images/images.worker.ts: [@cloudflare/wrangler]
packages/miniflare/test/plugins/images/index.spec.ts: [@cloudflare/wrangler]

workers-devprod · 2026-04-21T09:00:34Z

Codeowners approval required for this PR:

@cloudflare/wrangler

Show detailed file reviewers

packages/miniflare/src/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/plugins/core/index.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/core/constants.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/core/entry.worker.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/images/images.worker.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/shared/index.worker.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/shared/public-url.ts: [@cloudflare/wrangler]
packages/miniflare/src/workers/stream/binding.worker.ts: [@cloudflare/wrangler]
packages/miniflare/test/plugins/images/index.spec.ts: [@cloudflare/wrangler]

penalosa · 2026-04-21T12:20:39Z

Could you update this to follow the host detection logic added in #13234? Perhaps it would be simpler for that to merge first and then build on top of it.

mglewis · 2026-04-21T15:12:45Z

Could you update this to follow the host detection logic added in #13234? Perhaps it would be simpler for that to merge first and then build on top of it.

sure thing 👍 I'll wait for it to merge

mglewis · 2026-04-23T10:01:46Z

Could you update this to follow the host detection logic added in #13234? Perhaps it would be simpler for that to merge first and then build on top of it.

This has now been updated

penalosa

This is looking good! A few small comments and then we can get it in

workers-devprod · 2026-05-06T11:02:50Z

Codeowners approval required for this PR:

✅ @cloudflare/wrangler

Show detailed file reviewers

workers-devprod

Codeowners reviews satisfied

… mock

… stream binding pattern

workers-devprod added this to workers-sdk Apr 8, 2026

github-project-automation Bot moved this to Untriaged in workers-sdk Apr 8, 2026

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 994a828 to 8ce4647 Compare April 8, 2026 12:20

mglewis marked this pull request as ready for review April 8, 2026 12:21

mglewis requested a review from workers-devprod as a code owner April 8, 2026 12:21

workers-devprod requested review from a team and penalosa and removed request for a team April 8, 2026 12:21

This comment was marked as resolved.

Sign in to view

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch 4 times, most recently from 4a98618 to 4e488eb Compare April 10, 2026 11:00

penalosa reviewed Apr 13, 2026

View reviewed changes

Comment thread packages/miniflare/src/workers/core/entry.worker.ts Outdated

Comment thread packages/miniflare/src/index.ts Outdated

Comment thread packages/miniflare/src/index.ts Outdated

Comment thread packages/miniflare/src/workers/images/images.worker.ts

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 4e488eb to 1da4359 Compare April 21, 2026 09:00

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 1da4359 to d2be25f Compare April 21, 2026 11:11

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch 2 times, most recently from ddf8969 to 8fb009f Compare April 22, 2026 11:02

emily-shen requested a review from penalosa April 27, 2026 16:25

penalosa reviewed May 6, 2026

View reviewed changes

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 8fb009f to 6ca0346 Compare May 7, 2026 13:27

penalosa approved these changes May 7, 2026

View reviewed changes

workers-devprod approved these changes May 7, 2026

View reviewed changes

github-project-automation Bot moved this from Untriaged to Approved in workers-sdk May 7, 2026

mglewis force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 6ca0346 to 7e305cb Compare May 7, 2026 13:45

mglewis added 3 commits May 7, 2026 15:31

IMAGES-2191: improve variant URLs returned by miniflare hosted images…

818ae36

… mock

IMAGES-2191: use absolute variant URLs via publicUrl loopback

5e9397d

IMAGES-2191: move imagesServiceName into getGlobalServices - matching…

4a1f61c

… stream binding pattern

penalosa force-pushed the mattl/IMAGES-2191-better-variant-urls-for-hosted-images branch from 7e305cb to 4a1f61c Compare May 7, 2026 14:31

penalosa merged commit 5cf6f81 into cloudflare:main May 7, 2026
48 of 49 checks passed

github-project-automation Bot moved this from Approved to Done in workers-sdk May 7, 2026

workers-devprod mentioned this pull request May 7, 2026

Version Packages #13851

Merged

Conversation

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

Uh oh!

Implementation Details

Testing

Tests

Uh oh!

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

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new Bot commented Apr 8, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

workers-devprod commented Apr 8, 2026

Uh oh!

This comment was marked as resolved.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

workers-devprod commented Apr 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

penalosa commented Apr 21, 2026

Uh oh!

mglewis commented Apr 21, 2026

Uh oh!

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

Uh oh!

Uh oh!

penalosa left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

workers-devprod commented May 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

workers-devprod left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

mglewis commented Apr 8, 2026 •

edited

Loading

changeset-bot Bot commented Apr 8, 2026 •

edited

Loading

pkg-pr-new Bot commented Apr 8, 2026 •

edited

Loading

workers-devprod commented Apr 21, 2026 •

edited

Loading

mglewis commented Apr 23, 2026 •

edited

Loading

workers-devprod commented May 6, 2026 •

edited

Loading