wealth/docs/decisions/0010-island-sprite-and-font...

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.ts export with both: withIconSprite(withFontCopy(config)).
    • tools/icon-sprite-plugin builds the sprite from icons/*.svg with svgo and writes it to ICON_SPRITE_URL (/icons/symbol-defs.v<N>.svg).
    • tools/font-copy-plugin copies fonts/ byte for byte into public/fonts/.
  • Neither plugin adds a hash. The versions live in island constants.ts: ICON_SPRITE_VERSION, ICON_SPRITE_URL, and CRITICAL_FONT_URL. The Icon atom and the root layouts read them directly, so island needs no env.
  • Raise ICON_SPRITE_VERSION with every change to an icon or to the svgo step, in the same commit.
  • The plugins write in headers(), which only next dev and next build call. 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.ts sends Cache-Control: public, max-age=31536000, immutable for /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's island-env.ts, and the NEXT_PUBLIC_ISLAND_* variables are gone.
  • svgo loads only while the sprite is built, so next start doesn'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.