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

オープン
#2,379 コメント 1 件 リアクション 0 件 担当者 0 名 GitHub で見る

メンテナーはふだん 1 日以内に返信

まだ誰も着手していません。

評価

難易度
5/5
見積もり時間
1週間以上
初心者へのやさしさ
25/100
issue の種類
機能追加
明瞭さ
おおむね明確
活発さ
活発
技術スタック
nuxt, typescript

調査の方向性

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.

索引モデルが issue の本文から書いたものです。

説明

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

主要言語
TypeScript
スター
1.6k
フォーク
335
平均マージ
3日 13時間
マージ済み PR(30日)
15

環境構築

はじめの一歩

  1. issue を最後まで読み、次にプロジェクトのコントリビューションガイドを読みます。
  2. 着手することを issue にコメントします — 二人が同じ作業をするのを防げます。
  3. リポジトリをフォークし、ブランチを切って変更します。
  4. issue 番号を参照したプルリクエストを送ります。

nuxt/image のほかの issue

nuxt/image の issue をすべて見る

似ている issue

TypeScript の issue をもっと見る

新しい issue をメールで受け取る

初心者向けの GitHub issue を短くまとめたダイジェスト。