27 lines
2.0 KiB
Markdown
27 lines
2.0 KiB
Markdown
|
|
# 0012 Icon sprite under a fixed name, versioned in its link
|
||
|
|
|
||
|
|
Status: Accepted · Area: architecture · Date: 2026-10-05 · Decided by: user · Supersedes: 0010
|
||
|
|
|
||
|
|
## Context
|
||
|
|
|
||
|
|
0010 wrote the sprite as `symbol-defs.v<N>.svg`. The front-end-architect skill keeps `symbol-defs.svg` as a fixed name and puts the version in its link, and the user chose the skill's rule for this project.
|
||
|
|
|
||
|
|
## Decision
|
||
|
|
|
||
|
|
- island ships two build-time plugins, and each app wraps its `next.config.ts` export with both: `withIconSprite(withFontCopy(config))`. island's root `index.ts` leaves them out.
|
||
|
|
- `tools/icon-sprite-plugin` builds the sprite from `icons/*.svg` with svgo and writes it to `ICON_SPRITE_PATH` (`/icons/symbol-defs.svg`).
|
||
|
|
- `tools/font-copy-plugin` copies `fonts/` byte for byte into `public/fonts/`.
|
||
|
|
- Neither plugin adds a hash or a version to a file name. island `constants.ts` holds `ICON_SPRITE_VERSION`, and `ICON_SPRITE_URL` (`/icons/symbol-defs.svg?v=<N>`) built from it. The `Icon` atom links `${ICON_SPRITE_URL}#<name>`.
|
||
|
|
- Raise `ICON_SPRITE_VERSION` with every change to an icon or to the svgo step, in the same commit. Never reuse or lower it.
|
||
|
|
- The plugins write in `headers()`, skip unchanged files, write atomically, and warn in dev when a file changed without a new version or name. The sprite's first line stamps its version for that check.
|
||
|
|
- Each app sends `Cache-Control: public, max-age=31536000, immutable` for `/fonts/:path*` and `/icons/:path*`. The CDN keeps the same header and keeps the query string in its cache key. The sprite stays same-origin and root-relative. The generated files are gitignored.
|
||
|
|
|
||
|
|
## Alternatives
|
||
|
|
|
||
|
|
- Version in the file name (0010): a deploy that mixes old and new instances returns 404 for the new sprite, instead of old icons under the new `?v=`.
|
||
|
|
|
||
|
|
## Consequences
|
||
|
|
|
||
|
|
- During a rolling deploy, an old instance can answer `?v=<N+1>` with the old sprite, and a CDN would cache it for a year. Finish the rollout, or purge that URL, before the CDN caches it.
|
||
|
|
- A CDN that drops the query string from its cache key serves the old sprite after every bump.
|