wealth/docs/decisions/0012-sprite-version-in-link.md

27 lines
2.0 KiB
Markdown
Raw Normal View History

# 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.