wealth/docs/decisions/0008-island-asset-plugin.md

2.8 KiB

0008 Island asset plugin in each app's next.config

Status: Superseded by 0010 · Area: architecture · Date: 2026-10-04 · Decided by: user

Context

Fonts (0007) and the icon sprite live in island, but browsers load them from each app's public/ or a CDN. Something must put them there in dev and in build.

Decision

  • Island ships one build-time plugin, withIslandAssets in tools/asset-plugin (it replaces the planned icon-sprite-plugin). Each app wraps its next.config.ts export with it.
  • On next dev and next build (gated on PHASE_DEVELOPMENT_SERVER and PHASE_PRODUCTION_BUILD), it writes into the app's public/:
    • the fonts, under content-hashed names;
    • symbol-defs.svg, optimized with svgo, under a content-hashed name.
  • It adds the hashed paths, prefixed with the app's basePath, to the app's env (NEXT_PUBLIC_ISLAND_*) and an immutable Cache-Control header per file. The app's env/ reads them, and its bootstraps pass them to island's setEnv (iconSpritePath, fontUrls, with the app's CDN base prepended to the font paths).
  • The writes are idempotent and atomic (write a temp file, then rename), because Next can evaluate the config more than once per command.
  • The generated files are gitignored.
  • It is build-time only: import it from next.config.ts as @lumina/island/tools/asset-plugin. island's root index.ts leaves it out, an exception to re-exporting every module.
  • The sprite always loads from a root-relative, same-origin URL (/icons/symbol-defs.<hash>.svg#icon-x). <use href> is same-origin only in every engine, and CORS can't change that. To serve it through a CDN, put the CDN in front of the app's own domain, or add a beforeFiles rewrite. Never use an absolute CDN URL or assetPrefix.

Alternatives

  • An Nx target or predev/prebuild script: runs exactly once per command, but the user chose the next.config plugin.
  • Inlining the sprite in the root layout: no request, but it adds weight to every HTML response.

Consequences

  • Every app gets fonts and icons by registering one plugin; island stays the single source.
  • In dev, edits to island assets need a dev-server restart (Next watches only next.config), unless the plugin adds a watcher.
  • Other phases, next start included, get the config back unchanged: the build already inlined env and wrote the headers into its routes manifest, so production needs neither island's sources nor svgo. next typegen and other build-phase commands still run it.
  • Standalone and Docker builds must copy public/.
  • Nx's @nx/next plugin also calls the config with PHASE_PRODUCTION_BUILD, from the workspace root, to read distDir. So the plugin hashes when the config is evaluated but writes only in headers(), which only Next calls. Each app's Nx build outputs include public/icons and public/fonts.