Skip to content

Replace astro-icon with built-in icon system - #76

Draft
mvvmm wants to merge 2 commits into
mainfrom
replace-astro-icon
Draft

Replace astro-icon with built-in icon system#76
mvvmm wants to merge 2 commits into
mainfrom
replace-astro-icon

Conversation

@mvvmm

@mvvmm mvvmm commented Aug 10, 2026

Copy link
Copy Markdown
Contributor

What & why

Replaces astro-icon with a built-in icon system owned by Nimbus. The motivation is the incremental build cache instability reported in cloudflare-docs PR #32438: astro-icon stamps a generated lastModified timestamp into the virtual:astro-icon module on every build, which invalidates Astro's incremental build cache for thousands of pages. The package hasn't had a commit in 2+ years, so patching upstream isn't viable.

What changed:

  • New Vite plugin (icon-virtual.ts) providing virtual:nimbus/icons — auto-detects @iconify-json/* packages from the consumer's package.json, loads local SVGs from src/icons/, processes them with @iconify/tools (cleanup, monochrome→currentColor, SVGO). Deliberately omits lastModified from the exported collection so the module content is deterministic across builds.
  • New Icon.astro component (@cloudflare/nimbus-docs/components/Icon.astro) — drop-in replacement for astro-icon's <Icon>. Same API: name, size, width, height, is:inline, title, desc, plus all <svg> attributes. Default export.
  • Integration wiring — the icon plugin is auto-enabled from nimbus() via a new icons option (default on, false to disable). Type injection for virtual:nimbus/icons in astro:config:done.
  • Starter + www migration — all 41 component files updated from import { Icon } from "astro-icon/components" to import Icon from "@cloudflare/nimbus-docs/components/Icon.astro". astro-icon removed from astro.config.ts and package.json in both nimbus-starter-source and apps/www.
  • css-tree/csso browser bundle redirect — upgrading to @iconify/tools@5 (latest, no audit findings) changed the pnpm resolution tree, exposing a pre-existing bug where css-tree@3 and csso use createRequire(import.meta.url) to load JSON files at runtime, breaking Vite's prerender bundling (csstree/csstree#314, svg/svgo#2149). Fixed by redirecting bare css-tree and csso imports to their browser bundles (dist/csstree.esm, dist/csso.esm) which have JSON data inlined. The redirect uses both a Vite resolveId hook (for Rollup) and optimizeDeps.esbuildOptions.alias (for esbuild pre-bundling).

Why Nimbus owns this:

  • The icon system is framework infrastructure (build-time virtual module, SVG processing, iconify collection loading) — not taste/layout that belongs in starter source.
  • Owning it means we control the cache key contract and can fix issues without waiting on an unmaintained package.
  • The @iconify/tools / @iconify/utils / @iconify/types deps are already the same packages astro-icon depended on — no new transitive surface.

Checklist

  • A maintainer approved this work (lgtm+ on my issue or discussion), or I'm on the team
  • Correct tier (framework / starter / registry) per the boundary test
  • Edited packages/nimbus-starter-source/, not the templates branch
  • Changeset added (create-nimbus-docs changeset if the starter changed)
  • pnpm typecheck, pnpm -r test, and pnpm templates:check all green

@mvvmm
mvvmm force-pushed the replace-astro-icon branch 4 times, most recently from 58c728f to 86b1d88 Compare August 10, 2026 20:06
@mvvmm
mvvmm force-pushed the replace-astro-icon branch from 86b1d88 to acfac20 Compare August 10, 2026 20:06
@mvvmm mvvmm added the pr preview Publish a pkg.pr.new preview for this PR label Aug 10, 2026
@github-actions github-actions Bot removed the pr preview Publish a pkg.pr.new preview for this PR label Aug 10, 2026
@pkg-pr-new

pkg-pr-new Bot commented Aug 10, 2026

Copy link
Copy Markdown
pnpm add https://pkg.pr.new/@cloudflare/create-nimbus-docs@76
pnpm add https://pkg.pr.new/@cloudflare/nimbus-docs@76

commit: acfac20

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.

1 participant