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

2.5 KiB

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

Status: Accepted · 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/.