2.2 KiB
2.2 KiB
0010 Island icon-sprite and font-copy plugins, versioned and unhashed
Status: Superseded by 0012 · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0008
Context
0008's single asset plugin wrote the fonts and the svgo sprite into public/ under content-hashed names, and passed those names to island through env. An svgo or Next.js upgrade changes the bytes, so the hash renames the sprite even when no icon changed, and every visitor downloads it again. The user wants unchanged files to stay cached across deploys.
Decision
- island ships two build-time plugins, and each app wraps its
next.config.tsexport with both:withIconSprite(withFontCopy(config)).tools/icon-sprite-pluginbuilds the sprite fromicons/*.svgwith svgo and writes it toICON_SPRITE_URL(/icons/symbol-defs.v<N>.svg).tools/font-copy-plugincopiesfonts/byte for byte intopublic/fonts/.
- Neither plugin adds a hash. The versions live in island
constants.ts:ICON_SPRITE_VERSION,ICON_SPRITE_URL, andCRITICAL_FONT_URL. TheIconatom and the root layouts read them directly, so island needs no env. - Raise
ICON_SPRITE_VERSIONwith every change to an icon or to the svgo step, in the same commit. - The plugins write in
headers(), which onlynext devandnext buildcall. They skip unchanged files, write atomically (temp file, then rename), and warn in dev when a file changed under the same version. - Each app's
next.config.tssendsCache-Control: public, max-age=31536000, immutablefor/fonts/:path*and/icons/:path*. Configure the same header on the CDN. - The sprite always loads from a root-relative, same-origin URL, because
<use href>never loads across origins. - The generated files are gitignored.
Alternatives
- Content hashes (0008): automatic, but a pipeline change renames the files and empties every visitor's cache.
Consequences
- island's
env/module, the app'sisland-env.ts, and theNEXT_PUBLIC_ISLAND_*variables are gone. - svgo loads only while the sprite is built, so
next startdoesn't need it. - Shipping a changed icon or svgo config without a version bump leaves visitors on the old sprite for a year. Review blocks it, and the dev-time warning helps catch it.