# 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..svg#icon-x`). `` 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`.