fix(docs): bundle navigation icons to prevent client-nav flash

[benjamincanac]

Problem

Docs navigation icons (e.g. on /docs/4.x/getting-started/installation) flash in on client-side navigation. They render in @nuxt/icon's CSS mode (class="iconify i-lucide:book-marked"). On a hard refresh the mask CSS is inlined via SSR (onServerPrefetch), so it's fine — but on client-side route changes the icon data isn't in the client bundle, so it's fetched from the iconify API and the CSS rule is injected after paint → flash.

Icons used only by the remote docs nav (md frontmatter navigation.icon + .navigation.yml) can't be collected automatically at build time:

• clientBundle.scan skips them — remote docs are cloned under the .data dot-dir, ignored under tinyglobby dot:false.
• Parse hooks (content:file:beforeParse) don't help — @nuxt/content restores its cache on CI (✔ … 972 cached, 0 parsed), so nothing is parsed and the hook never fires.
• Globbing the raw .data/content files doesn't help either — repos aren't re-cloned on cached CI builds.

(All three verified empirically with local builds.)

Fix

Inline the remote-docs-only icon list into icon.clientBundle.icons — the only build-state-independent source (data loaded from the installed @iconify-json/* packages at build). Collected across all three served versions (nuxt/nuxt 3.x, 4.x, main) — important because some icons are version-specific (e.g. vscode-icons:folder-type-app only appears in 4.x's app/ directory structure). Every entry is validated against the installed packages (an unresolved clientBundle.icons entry would fail a production build).

Local content (deploy, blog, …) and app icons stay covered by scan; its glob is widened to include .ts (app config) and **/.*.{yml,yaml} (local .navigation.yml dotfiles).

Refreshing the list

Regenerate when docs add icons — grep all three branches for i-<collection>-<name> and subtract what scan already covers (app + local content/).

Verification

Local production build: client bundle 215 → 262 icons (143.57 KB, under the 256 KB limit), including all folder-type-*/file-type-* docs nav icons. Cross-checked the 3.x/4.x/main branches against the bundle — initial main-only list missed vscode-icons:folder-type-app + simple-icons:google; both now included.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
nuxt	Ready	Preview, Comment	Jun 25, 2026 4:18pm

[coderabbitai]

📝 Walkthrough

Walkthrough

The client bundle icon scan setting now uses an explicit globInclude pattern list instead of a boolean flag. The listed patterns cover Vue, JavaScript, TypeScript, Markdown, MDC, YAML, YML, and dot-prefixed YAML/YML files.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~4 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Description check	✅ Passed	The description discusses the same icon bundle scanning change and the added file patterns in nuxt.config.ts.
Title check	✅ Passed	The title accurately summarizes the main change: bundling navigation icons at build time to avoid client-side flashes.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch chore/icon-scan-glob

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}