2.8 KiB
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,
withIslandAssetsintools/asset-plugin(it replaces the plannedicon-sprite-plugin). Each app wraps itsnext.config.tsexport with it. - On
next devandnext build(gated onPHASE_DEVELOPMENT_SERVERandPHASE_PRODUCTION_BUILD), it writes into the app'spublic/:- 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'senv(NEXT_PUBLIC_ISLAND_*) and an immutableCache-Controlheader per file. The app'senv/reads them, and its bootstraps pass them to island'ssetEnv(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.tsas@lumina/island/tools/asset-plugin. island's rootindex.tsleaves 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 abeforeFilesrewrite. Never use an absolute CDN URL orassetPrefix.
Alternatives
- An Nx target or
predev/prebuildscript: 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 startincluded, get the config back unchanged: the build already inlinedenvand wrote the headers into its routes manifest, so production needs neither island's sources nor svgo.next typegenand other build-phase commands still run it. - Standalone and Docker builds must copy
public/. - Nx's
@nx/nextplugin also calls the config withPHASE_PRODUCTION_BUILD, from the workspace root, to readdistDir. So the plugin hashes when the config is evaluated but writes only inheaders(), which only Next calls. Each app's Nxbuildoutputs includepublic/iconsandpublic/fonts.