[ogawa0071]

Closes #441

Summary

This adds image optimization compatible with next/image in Next.js 16, backed by the Cloudflare Images binding.

• Image and getImageProps() in @void/react, @void/vue, @void/svelte and @void/solid. They take the props of next/image and render the same <img> attributes, including srcset.
• @void/react/image has the next/image module shape, so resolve.alias: { 'next/image': '@void/react/image' } compiles existing components unchanged.
• images in void.config.ts takes the keys, types and defaults of images in next.config.js, including loader and loaderFile.
• /_void/image follows /_next/image: the same url/w/q validation and 400 messages, Accept negotiation and caching headers. It transforms images with env.IMAGES and caches results in caches.default.
• IMAGES is inferred from Image and getImageProps imports and from env.IMAGES reads. inference.bindings.images enables, renames or removes it.
• import hero from './hero.png?image' returns StaticImageData ({ src, width, height }).

Most of the diff is tests and checked-in fixtures:

Area	Added	Removed	Files
Tests and fixtures	13,519	17	57
void/image core and endpoint	3,441	0	22
Plugin wiring, inference, routing and CLI	2,368	66	33
Adapters	1,712	39	20
Docs	786	12	14
Manifests, schema, build config and CI script	270	10	8

How it works

• Shared core. void/image holds prop resolution, srcset selection, the built-in loaders, pattern matching and the config types, ported from Next.js 16.4.2. It runs in Workers and browsers. Patterns are compiled with picomatch at build time, in Node.
• Config transport. The plugin prepends a virtual:void/image-config import to the void/image entry in every environment, so server rendering and hydration use the same config and loaderFile. void/image is excluded from dependency optimization, so prebundling can't drop that import.
• Endpoint mounting. The generated route table mounts the endpoint after auth and user middleware, and before WebSocket hooks, routes and pages. It does so only for apps that use Image with the default loader, or that set inference.bindings.images. Apps without images generate the same code as before. Anonymous requests to the path skip the auth session lookup, and the path also skips self-host ISR and the SPA fallback.
• Local sources are requested through the app without client headers, like Next.js's internal request, so middleware that guards the path applies. An app 404 falls back to env.ASSETS.
• Remote sources follow Next.js: remotePatterns, maximumRedirects, maximumResponseBody and a 7-second timeout, without client headers. maximumResponseBody is capped at the binding's 20 MB input limit.
• Caching. Results are stored in caches.default, keyed on source, width, quality and negotiated format. Cached local sources are scoped to the deployment. Optimized ?image imports are fingerprinted, so they get public, max-age=315360000, immutable.
• Fallbacks. Animated GIF, PNG and WebP sources pass through unchanged, as do SVGs when dangerouslyAllowSVG is set, as in Next.js. A failed transformation serves the original and logs a warning. That includes error 9422, returned once the Images Free allowance is used up.

Workers Free and other targets

• The Images Free plan includes 5,000 unique transformations a month, so the feature is on by default under the Workers Free rule in AGENTS.md. Nothing probes Images entitlement.
• Apps that don't use Image, getImageProps or env.IMAGES emit no binding, var or route. Tests cover this.
• Void Platform has no Images binding. Managed builds render originals and void deploy warns, unless a custom loader or the cloudflare loader is set.
• node, bun and deno targets and output: "static" render originals unless a custom loader is set.
• images.loader: 'cloudflare' emits /cdn-cgi/image/... URLs for zones with transformations enabled. It adds no binding and no endpoint.

Decisions on the open questions

1. Static imports: ?image returns StaticImageData, and plain imports keep Vite's URL string. There is no opt-in to Next.js import semantics yet.
2. Blur placeholders: blurDataURL isn't generated. placeholder="blur" needs an explicit blurDataURL.
3. Void Platform: originals and a deploy warning, as above, until the platform can provide a binding.
4. Local sources served by routes: implemented as Next.js does, instead of static assets only. A route or page that answers the path supplies the image, without the visitor's cookies.
5. Durable cache: caches.default only.

Other choices worth reviewing:

• Redirect targets must also match remotePatterns. Next.js resolves each hop and refuses private addresses, but a Worker can't resolve DNS, and Miniflare can reach private networks in development.
• AVIF is skipped above 1,200 px, Cloudflare's limit. Quality is passed through without Next.js's AVIF scaling, which is tuned for sharp.
• ?image files are marked immutable in the client manifest, but they aren't passed to the hashed-file Worker bypass from fix(auth): keep static file cache policy for signed-in users, and skip the Worker for hashed chunks #552. Image file names and counts therefore can't turn that bypass off.

Differences from next/image

These are documented in docs/guide/images.md under "Migrating from next/image":

• The endpoint is /_void/image instead of /_next/image, and its cache status header is X-Void-Image-Cache.
• Static imports need ?image, and blurDataURL isn't generated.
• AVIF output is limited to 1,200 px wide, and maximumResponseBody to 20 MB.
• dangerouslyAllowLocalIP covers only localhost and IP addresses written in the URL, because hostnames aren't resolved.
• maximumDiskCacheSize, disableStaticImages and customCacheHandler are accepted with a warning and have no effect.

Not verified on Cloudflare

I tested with Miniflare's local Images binding, not a deployed Worker. The issue's "to verify" items are handled so that the outcome doesn't depend on the answer:

• Images binding in a Workers for Platforms namespace: not used. Void Platform renders originals.
• Error 9422: every transformation error serves the original, so the exact error shape doesn't matter.
• AVIF wider than 1,200 px: never requested from the binding.
• AVIF quality scaling: not applied.
• caches.default on workers.dev: if writes have no effect there, responses are still correct; images are just transformed again.
• Offline binding in development: width and format apply. q has no visible effect locally, which the guide documents.

Testing

• Markup parity: golden fixtures generated once from next@16.4.2 (getImgProps and the next/image component) for a table of props: fixed sizes, sizes, fill, preload, unoptimized, custom loaders, overrideSrc and each placeholder. They are checked in, so the repository doesn't depend on next.
• Endpoint: the expected 400 results come from running Next.js 16.4.2's ImageOptimizerCache.validateParams. Other cases cover format negotiation, the AVIF cap, the 9422 and passthrough fallbacks, cache keys and deployment scoping.
• Integration: image-endpoint.test.ts runs the endpoint against Miniflare's local binding, and image-route-generated.test.ts exercises the generated route table.
• Inference and deploy: apps without images emit no binding, var or route. Other cases cover overrides, custom names, vinext's imagesOptimizer() and native deploy validation.
• Adapters: tests for all four adapters, including preload links from page and island renderers.
• Packed consumer: .github/scripts/packed-consumer.mjs renders Image from the installed packages and requests /_void/image.

Run locally on this branch, merged with the current main:

• vp check, vp run check, vp run build:all, node test/check-playground-build-artifacts.mjs and vp run build:docs pass.
• vp test run --project unit --project unit-pglite --project cli-unit passes, except one HTTP proxy test that fails the same way on main in my environment.
• vp test run --project parallel-integration passes.
• The packed consumer check passes with pnpm (smoke suite).

Changes to existing tests

• packages/react/test/integration/md-layout-frontmatter.test.ts: the stub for the pages plugin now prebundles React, as the real plugin does. @void/react now imports react-dom for Image, and discovering it during hydration made Vite re-optimize dependencies and reload the page mid-test.
• Other existing tests only gain cases, the new needsImages and usesImageOptimizer fields, or allowlist entries such as __VOID_IMAGES_BINDING in the kitchen-sink leak check.

[socket-security]

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	@​types/​picomatch@​4.0.3

View full report

[yangshun]

@ogawa0071 checking in on this PR 😄