2.0 KiB
2.0 KiB
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.tsexport with both:withIconSprite(withFontCopy(config)). island's rootindex.tsleaves them out.tools/icon-sprite-pluginbuilds the sprite fromicons/*.svgwith svgo and writes it toICON_SPRITE_PATH(/icons/symbol-defs.svg).tools/font-copy-plugincopiesfonts/byte for byte intopublic/fonts/.
- Neither plugin adds a hash or a version to a file name. island
constants.tsholdsICON_SPRITE_VERSION, andICON_SPRITE_URL(/icons/symbol-defs.svg?v=<N>) built from it. TheIconatom links${ICON_SPRITE_URL}#<name>. - Raise
ICON_SPRITE_VERSIONwith 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, immutablefor/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.