Skip to content

fix(image): serve /_next/image on Nitro production builds and honor images.minimumCacheTTL - #3741

Open
AhmedElBanna80 wants to merge 13 commits into
cloudflare:mainfrom
AhmedElBanna80:fix/nitro-image-optimization
Open

AhmedElBanna80 wants to merge 13 commits into
cloudflare:mainfrom
AhmedElBanna80:fix/nitro-image-optimization

Conversation

@AhmedElBanna80

Copy link
Copy Markdown
Contributor

Closes #3740.

Stacked on #3734, which adds the x-nextjs-cache: MISS header. The commits before the last one are that PR; only the last commit is new here. I will rebase once #3734 merges.

What this changes

On a Nitro production build, /_next/image now answers with the image instead of a 302 to the source. Workers, the Node server and dev are unchanged.

I reworked the earlier attempt to address the points raised on #3734:

  • minimumCacheTTL comes from the config. images.minimumCacheTTL is added to the images type, passed through the generated entries as part of imageConfig, and defaults to 14400 as in Next.js. The response is public, max-age=<max(source max-age, minimumCacheTTL)>, must-revalidate. Nothing is hard-coded.
  • No globalThis.__nitro__ check in the handler. The handler takes a new option, resolveImageSourceFetch, which returns a function that fetches a same-origin source. The generated entry sets it only when the Nitro plugin was detected at build time (the existing hasNitroPlugin), through a new serveImagesInProcess entry option. On other hosts the option is not emitted and nothing is read. Tests inject a fake fetch, so they touch no globals.
  • Where the Nitro app comes from. nitro/app has its own fetch, but importing it from the RSC environment would bundle a second Nitro app, so getNitroImageSourceFetch reads globalThis.__nitro__.default, which Nitro declares in its types. That is the one remaining read of that global, and it is confined to Nitro builds. If you know a better hook for the host fetch, I will switch to it.
  • Immutable only for hashed media. images.minimumCacheTTL aside, immutable is used only when the source is under /_next/static/media/ or /_next/static/immutable/media/ after removing the configured basePath and the path part of assetPrefix. The path is normalised before the check (dot segments and percent-encoding resolved, including a double-encoded slash), so a traversal out of that directory is treated as an ordinary public file. Next.js checks basePath only; assetPrefix is included because vinext writes build assets under it.

The security properties are kept: the sub-request carries none of the client's headers, only Content-Type, Content-Length, ETag, Last-Modified and Cache-Control are copied from the source (never Set-Cookie), a non-image source gets a 400, and only same-origin paths are accepted (the existing parameter validation rejects the rest).

Tests

  • tests/app-rsc-handler.test.ts: production answers 200 directly (not 302), Cache-Control from minimumCacheTTL, a longer source max-age wins, immutable only for hashed media with and without a path assetPrefix, traversal (plain, %2e%2e, double-encoded) not immutable, no client headers on the sub-request, Set-Cookie not forwarded, non-image source and cross-origin url rejected, dev and "no host available" still redirect.
  • tests/shims.test.ts: getNitroImageSourceFetch.
  • tests/app-router-next-config-codegen.test.ts: the option is emitted only with serveImagesInProcess.

I checked the traversal test by replacing the path normalisation with the raw path; the two immutable tests fail, and pass again after restoring it. vp check is clean for the touched files. I could not run the Nitro example end to end here, so I have not run the Next.js og-api e2e against a real Nitro build.

No user-facing docs change: images.minimumCacheTTL is a Next.js option that is now honoured on this path.

AhmedElBanna80 and others added 7 commits October 7, 2026 00:37
Reverts the four earlier commits on this branch so the header can be
reworked from vinext's actual image-serving paths:

- 33ef8eb fix(image): send x-nextjs-cache on /_next/image responses
- fcab81a fix(image): answer /_next/image from the Nitro app in production
- 793fedd fix(image): match Next.js caching and source headers on the Nitro image path
- ec9b824 fix(image): resolve the source path before deciding a Nitro image is immutable
Next.js sends X-Nextjs-Cache on every successful /_next/image response:
MISS when the optimizer ran for the request, HIT or STALE when its image
cache served the bytes. A 304 and error responses carry no header.

vinext keeps no cache of optimized images on any runtime. Every 200 from
the image endpoint is transformed (Cloudflare Images binding) or passed
through from the source for that request. That is what Next.js does with
its image cache disabled (images.maximumDiskCacheSize: 0), where every
200 is a MISS, so the image handlers now send MISS:

- handleImageOptimization (Workers, App and Pages Router) sets it with the
  other headers shared by transformed and passed-through responses.
- The Node production server sets it only on responses that carry the
  image bytes, so a 304 revalidation stays without it.

Dev and the App Router without an image optimizer still redirect to the
source, which is not an image response.

Fixes cloudflare#3733
@pkg-pr-new

pkg-pr-new Bot commented Oct 7, 2026 •

Copy link
Copy Markdown

Open in StackBlitz

@vinext/cloudflare

npm i https://pkg.pr.new/@vinext/cloudflare@3741

create-vinext-app

npm i https://pkg.pr.new/create-vinext-app@3741

@vinext/types

npm i https://pkg.pr.new/@vinext/types@3741

vinext

npm i https://pkg.pr.new/vinext@3741

@cloudflare/workers-response-store

npm i https://pkg.pr.new/@cloudflare/workers-response-store@3741

commit: b00f696

@github-actions

github-actions Bot commented Oct 7, 2026 •

Copy link
Copy Markdown
Contributor

Performance benchmarks

Compared b00f696 against base 8659957 using alternating same-runner rounds. Next.js was unchanged and skipped.

0 improved · 1 regressed · 6 within ±1.5%

Scenario Framework Baseline Current Change
Client bundle size (gzip) vinext 152.3 KB 152.3 KB ⚫ 0.0%
Client entry size (gzip) vinext 140.6 KB 140.6 KB ⚫ 0.0%
Dev server cold start vinext 2.77 s 2.75 s ⚫ -0.9%
Dev server cold start (large Pages Router app) vinext 24.38 s 24.32 s ⚫ -0.3%
Production build time vinext 3.59 s 3.61 s ⚫ +0.6%
RSC entry closure size (gzip) vinext 142.6 KB 146.0 KB 🔴 +2.4%
Server bundle size (gzip) vinext 250.2 KB 253.6 KB ⚫ +1.4%

View detailed results and traces

🟢 improvement · 🔴 regression · ⚫ change below 1.5% · paired base/head

@AhmedElBanna80

Copy link
Copy Markdown
Contributor Author

One more case this PR does not cover yet: the Pages Router under Nitro.

On a Nitro production build of a Pages Router app, /_next/image answers 404 rather than 302. serveFilesystemRoute in pages-request-stage-entry.ts returns false as soon as there is no assets binding, before the image branch, and Nitro has no ASSETS:

if (!assets) return false;
if (isImageOptimizationPath(requestPathname)) {

The Next.js test that shows it is test/e2e/next-image-new/loader-config-default-loader-with-file. It is a Pages Router app whose images.loaderFile returns /_next/image/?url=..., and it checks that the <img> loads (naturalWidth !== 0). With #3686 applied, src and srcset match, but the image request 404s.

Repro: build a Pages Router app with nitro({ preset: 'node' }), put logo.png in public/, and request /_next/image?url=%2Flogo.png&w=828&q=75.

I would like to extend this PR to cover the Pages Router as well, by feeding the same Nitro source fetch to the Pages handler when there is no assets binding. I would also reject a url that points back at /_next/image with a 400, as Next.js does. Or I can open it as a separate PR if you prefer to keep this one App Router only.

…imization

# Conflicts:
#	packages/vinext/src/server/app-rsc-handler.ts
#	packages/vinext/src/server/image-optimization.ts
@clanky-the-clanker

Copy link
Copy Markdown

This pull request was not reviewed automatically because its author does not have write access to this repository. A maintainer with write access can start a review by commenting clanky review (or clanker review or @clanky-the-clanker review), optionally followed by instructions (e.g. clanky review focus on the retry logic).

…ization

# Conflicts:
#	packages/vinext/src/entries/app-rsc-entry.ts
#	packages/vinext/src/index.ts
@AhmedElBanna80

Copy link
Copy Markdown
Contributor Author

@james-elicx Could you take a look when you have a moment? CI is green and the branch merges cleanly. This is one of five related PRs (#3686, #3741, #3759, #3768, #3771); I'm happy to rebase or split any of them if that makes reviewing easier. Thanks!

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Nitro: /_next/image redirects to the source instead of serving the image (and images.minimumCacheTTL is ignored)

3 participants