RFC: More deterministic build-time image generation (conditionally rendered images aren't generated in SSG)

Aperta
#2,379 1 commento 0 reazioni 0 assegnatari Vedi su GitHub

I maintainer di solito rispondono entro 1 giorno

Nessuno ha ancora preso questa issue.

Valutazione

Difficoltà
5/5
Tempo stimato
Più di una settimana
Idoneità per principianti
25/100
Tipo di issue
Funzionalità
Chiarezza
Abbastanza chiara
Stato di attività
Attiva
Stack tecnologico
nuxt, typescript

Direzione di ricerca

Start by reading the getImage() prerender registration path described in the issue, then inspect the related issues #446, #861, #1515, and #1608 for prior discussion. Reproduce with Nuxt 4.6.4 and @nuxt/image 2.2.1 using nuxt generate, then serve .output/public and check the conditional image URLs, including both density variants. The issue proposes several possible directions but leaves the design and scope open.

Scritto dal modello di indicizzazione a partire dal testo della issue.

Descrizione

Hi Nuxt team, first, thank you for all the work on Nuxt and @nuxt/image. 🙏

I'd like to bring up a problem I keep running into with nuxt generate, and share some ideas. I might be missing some background on why things work this way, so please correct me if I'm wrong.

The problem

In SSG, only images that get rendered during prerender are generated. If a <NuxtImg> is inside v-if, <ClientOnly>, a modal, or anything that only shows up on the client, its /_ipx/... file never gets created, and the image is broken (404) after deploy.

The build passes with no warning, and nuxt dev works fine, so you usually only find out in production.

I first hit this in 2025 (I commented in #1515). Some of my images were rendered after an IntersectionObserver fired, and they all broke after switching to nuxt generate. In the end I moved the whole site to vite-imagetools, because it optimizes at build time based on imports, so it doesn't matter whether the image is rendered or not.

Reproduction

[email protected], @nuxt/[email protected], image: { format: ['webp'] }, each image width="200" (default 1x 2x). After nuxt generate, I served .output/public with a static server and also checked in a real browser (clicking the button that opens the v-if images):

Case 1x 2x
always rendered ✅ 200 ✅ 200
v-if, shown on click ❌ 404 ❌ 404
v-if, shown after onMounted ❌ 404 ❌ 404
v-show, hidden at first ✅ 200 ✅ 200
<ClientOnly> ❌ 404 ❌ 404
v-if + useImage() workaround from #1608 ✅ 200 ❌ 404

The workaround helps, but it only registers the exact URL you call, so the 2x from densities is still missing.

From reading the code: getImage() registers the URL through the x-nitro-prerender header only when it runs on the server during prerender. If a component isn't rendered in SSR, nothing registers its images.

Why I think it matters

  • Most projects just use the default IPX. Small and medium sites often deploy static files to their own server and don't pay for an image CDN. Unless you're on Netlify / Vercel / Amplify (auto-detected), this is exactly the setup that breaks.
  • It's easy to hit. Even a simple Nuxt Content blog usually has a light/dark logo, an image lightbox, a mobile menu, or a carousel.
  • The Static Images docs only mention ssr: false, not conditional rendering. (#446 about modals was closed as documented.)

For reference, Next.js has a similar story: Discussion vercel/next.js#19065 ("Optimize images during next build", open since 2020, 400+ upvotes) shows how much people want build-time optimization; their reason for not doing it is build time. The community package next-image-export-optimizer simply generates every image in a folder for a fixed list of widths, and I tested that conditionally rendered images work fine with it.

Ideas

Just rough ideas, I'm sure the team knows better what fits:

  1. Make the list of generated images predictable, instead of depending on what rendered:
    • collect <NuxtImg> with static props at compile time (similar to how vite-imagetools works),
    • opt-in: generate all images in a folder × a fixed list of widths/formats (this also covers dynamic src),
    • keep the current prerender crawling as well.
  2. Don't 404 on unknown widths. If a width wasn't generated, snap up to the next generated width, or fall back to a format-only version (original size, still webp).
  3. Tell the user. Print what couldn't be optimized at the end of nuxt generate, maybe a strict mode for CI, and a warning in dev when the client asks for a /_ipx URL that SSR never saw.
  4. Build-time option for SSR too. With a Node server, IPX transcodes at runtime, which uses CPU and memory on the same server as SSR, and redoes the work after every deploy unless there's a CDN in front. For local images known at build time, it would be nice to choose build-time generation instead.

Remote images (CMS, user uploads) can't be known at build time, so they'd still need a CDN. That's out of scope.

A maintainer mentioned in #861 that pre-generating would be possible if the sizes/modifiers are specified in config, so I hope this isn't too far from what the team had in mind.

I'm happy to start with a docs PR about the current limitation, and I can share a small prototype of the folder × widths idea. Thanks again for everything you do for Nuxt! 💚

Related: #446, #861, #1515, #1608

Lingua principale
TypeScript
Stelle
1.6k
Fork
335
Merge medio
3g 13h
PR unite (30g)
15

Preparare l'ambiente

Come iniziare

  1. Leggi tutta la issue e poi la guida ai contributi del progetto.
  2. Commenta sulla issue per dire che te ne occupi tu — evita che due persone facciano lo stesso lavoro.
  3. Fai un fork del repository e lavora su un branch.
  4. Apri una pull request che faccia riferimento al numero della issue.

Altre issue di nuxt/image

Tutte le issue di nuxt/image

Issue simili

Altre issue su TypeScript

Ricevi le nuove issue nella tua casella

Un breve riepilogo di issue GitHub adatte ai principianti.