What it is

rareicon.com. An Astro/Starlight site whose bulk is an icon catalog: 1254 terms, each holding every visual variant of one concept, with the SVG inline in the page’s frontmatter so a variant can be searched, recoloured and copied without a second request.

One version and one image cover the whole thing, because the site and the process that serves it have no separate lifecycle. A new page is a new deploy either way.

Layout

apps/rareicon/web/
  astro/    the Starlight site, builds static to astro/dist
  server/   rareicon-web, the axum that serves that dist
  e2e/      Playwright, drives the pair
  codegen/  proto-to-zod.mjs, and icons/ -- the pack scraper

Where the icons come from

codegen/icons/ pulls from the upstream FOSS packs — Lucide, Tabler, Phosphor, Simple Icons, Game Icons and a set of Iconify bundles — and emits one MDX per concept under astro/src/content/docs/icons/. It is opt-in and its output is committed: pulling thousands of SVGs from the internet is not something a build should do on its own, and dedup-keys.json is the ledger that keeps a re-run deterministic.

The licence of each term travels with it, in default_license on the page, and is what the site renders on the term’s own page.

The schema

codegen/proto-to-zod.mjs reads schemas/proto/kbve/icon/v1/icon.proto and writes the Zod the content collection validates against. The proto is the source of truth for what an icon term is; nothing in the site restates it.

A field added to IconTerm and not to the collection schema is a field Astro strips on the way in, silently, page by page — which is the failure mode that makes generating this worth the generator.

What the server does

Static files. ServeDir per asset prefix with brotli and gzip variants precompressed at image build time, directory requests rewritten to index.html, and Astro’s own 404.html served at a 404 status so a typo’d URL is not indexed as a page.

It links axum and tower-http and nothing else. The KBVE tree’s equivalent reached for the shared kbve crate to get the same router and paid for it in diesel, reqwest, argon2 and jsonwebtoken — a database driver and a password hasher in a process that hands out HTML.

There is no API here. The dynamic half of RareIcon is rareicon-server, and this process knows nothing about it.

Deploying

A bump to the version: in this doc’s frontmatter, on the default branch, is the release. The build reads it, stamps it into the version.toml and Cargo.toml it compiles from, and publishes it as the tag; the deploy job then opens a merge request writing that tag into the manifest this doc names, and the manifests move when it is merged.

version.toml is still watched, so bumping it works too, and sh tools/version-sync/sync.sh bump rareicon-web <version> writes both plus the Cargo.toml the binary reports itself from. See apps/rareicon/ci.yml and tools/version-sync.