30 lines
2.2 KiB
Markdown
30 lines
2.2 KiB
Markdown
# 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.
|