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

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