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

Abierto
#2,379 1 comentario 0 reacciones 0 asignados Ver en GitHub

Los mantenedores suelen responder en 1 día

Nadie ha tomado este issue todavía.

Evaluación

Dificultad
5/5
Tiempo estimado
Más de una semana
Aptitud para principiantes
25/100
Tipo de issue
Nueva funcionalidad
Claridad
Bastante claro
Estado de actividad
Activo
Stack tecnológico
nuxt, typescript

Línea de trabajo

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.

Escrito por el modelo de indexación a partir del texto del issue.

Descripción

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

Lenguaje dominante
TypeScript
Estrellas
1.6k
Forks
335
Merge medio
3 d 13 h
PR fusionados (30 d)
15

Preparar el entorno

Primeros pasos

  1. Lee el issue completo y luego la guía de contribución del proyecto.
  2. Comenta en el issue que vas a ocuparte — evita que dos personas hagan lo mismo.
  3. Haz un fork del repositorio y trabaja en una rama.
  4. Abre un pull request que haga referencia al número del issue.

Más de nuxt/image

Todos los issues de nuxt/image

Issues similares

Más issues de TypeScript

Recibe los nuevos issues en tu correo

Un resumen breve de issues de GitHub para principiantes.