33 lines
2.8 KiB
Markdown
33 lines
2.8 KiB
Markdown
# 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`.
|