Distribution
How Semetrika is built, packaged, and delivered to consumers.
This document is maintainer-facing. Consumers who want to include Semetrika in a site should read Installation instead.
The model
Semetrika is distributed as tagged GitHub releases served by jsDelivr in GH-mode. There is no npm package and no plan to publish one - Semetrika is intended to be embedded as static assets, not consumed as a dependency.
Three channels reach a consumer, all rooted at the same tagged commit:
| Channel | URL shape | Use case |
|---|---|---|
| jsDelivr CDN | https://cdn.jsdelivr.net/gh/drevops/semetrika@TAG/dist/semetrika.min.css | Drop-in <link> / <script>, no install |
| Bundler install | npm install github:drevops/semetrika#TAG | Vite, webpack, other build pipelines |
| Release-asset download | https://github.com/drevops/semetrika/releases/download/TAG/semetrika.min.css | Self-host, vendor, air-gapped environments |
TAG is either a release tag (v0.1.0), a range (v0), a commit SHA, or the
main branch. The consumer page covers the trade-offs in
Choosing a ref.
Build pipeline
yarn build - the CLI's build command in packages/cli/src/commands/build.js -
produces dist/ locally and in CI. The pipeline uses:
- Lightning CSS - native Rust, handles
@layer, zero-config. Produces minified CSS + source maps. - esbuild - JS bundler (IIFE output). Source
files are IIFE-wrapped, but at least one utility (
popout) imports@floating-ui/dom, so the JS pipeline runs through esbuild's bundler to resolve external imports and produce a self-contained<script>tag target. src/foundation/icons/build-sprite.util.js- refreshes the icon sprite before copying it todist/.
Shipped assets - the sprite and the font faces - are copied into dist/ rather
than inlined, so a consumer can cache, subset, or replace them independently of
the stylesheet.
Both Lightning CSS and esbuild are single-binary, zero-config, and run in well under a second for this codebase.
Build output
dist/ contains:
| File | Contents |
|---|---|
semetrika.css / .min.css / .min.css.map | Full combined bundle: layers + variables + options + framework + foundation + utilities + components |
semetrika-variables.css / .min.css / .min.css.map | Tokens only: layers + variables + options. Reference file - see below. |
semetrika.js / .min.js / .min.js.map | Bundled utilities + component JS (IIFE, external @floating-ui/dom inlined) |
icons.svg | Icon sprite (one <symbol> per icon, holding one or both of its variant artworks) |
fonts/<typeface>/<face>.woff2 | The bundled typefaces, one directory per family holding a variable file per style, plus their license |
Source maps are generated for minified files only - unminified files are already readable, source maps for them would double the output footprint.
fonts/ has to sit beside semetrika.css, because the @font-face rules
address each bundled face relative to the stylesheet. That is what lets the
same bundle work from a CDN, from node_modules, and from a sub-path on a
consumer's own host without being told where it was deployed. Serving the CSS
without the directory beside it falls back to the generic the tokens name after
the family.
Bundled and remote faces
Semetrika bundles the typefaces its pages are mostly made of - headings and body copy - so rendering a page tells no font host anything about the visitor, and an intranet or air-gapped deployment renders the same as a public one. Where the bundle itself is loaded from stays the consumer's decision: serving it from a CDN puts that host in the request path, as the delivery table above shows.
The monospace face is the exception, and a deliberate one. It is served from
Google Fonts rather than shipped, so it costs a third-party request - but only on
pages that render code, and it falls through to a system stack when the request
cannot be made. Carrying one of each keeps both delivery modes exercised rather
than merely described, and assets.fonts.items.<role>.source in
semetrika.spec.json is where a consumer reads which is which.
A consumer who wants no outbound request at all overrides --font-family-mono
with a system stack, or supplies their own bundled face and @font-face rule.
Bundle naming follows the universal industry convention ({name}.css /
{name}.min.css / {name}.min.css.map) shared by Bootstrap, Tailwind, Pico,
Bulma, Water, Simple, and others.
Release flow
.github/workflows/release-nodejs.yml runs on tag push. Its release-nodejs job:
- Checks out the tagged commit.
- Installs dependencies (
yarn install --frozen-lockfile). - Builds (
yarn build). - Attaches every file under
dist/to the GitHub release viasoftprops/action-gh-release.
That makes the release-asset URL pattern
(github.com/drevops/semetrika/releases/download/TAG/<file>) work immediately
on tag push, with no extra infrastructure.
A second job, release-site, builds the documentation site and deploys it to
a password-protected Netlify project. docs/README.md lists the secrets it
reads.
Gap: jsDelivr GH-mode and bundler-install both need dist/ in the tag tree
dist/ is gitignored. The release workflow attaches built files to the
release but does NOT commit them into the source tree at the tag. This
breaks two of the three channels:
- jsDelivr GH-mode serves files from the git tree at the referenced ref.
Without
dist/in the tree,cdn.jsdelivr.net/gh/drevops/semetrika@TAG/dist/*returns 404. - Bundler install clones the source repo at the ref. Without
dist/in the tree (or apreparescript that builds on install), the consumer ends up with no bundle innode_modules/semetrika/dist/.
This gap must be closed before the first tag is cut. Two paths to a fix:
- Commit
dist/at tag time - the release workflow doesyarn build, thengit add -f dist/, then re-tags the commit (or pushes a build commit before the tag). Cleanest from a consumer perspective, all three channels resolve to the same git tree state. - Add a
preparescript -package.jsonrunsyarn buildon install. Fixes the bundler-install channel only; jsDelivr GH-mode still needs the first path.
The minimum viable fix for full coverage is the first path.
Subresource Integrity
For consumers who want SRI hashes in their <link> and <script> tags,
generate them at release time:
printf 'sha384-%s\n' "$(openssl dgst -sha384 -binary dist/semetrika.min.css | openssl base64 -A)"
jsDelivr also exposes SRI hashes in its API for any byte-stable ref:
https://data.jsdelivr.com/v1/package/gh/drevops/semetrika@v0.1.0.
The consumer-facing Subresource Integrity section covers how to consume these.
Alternatives considered
npm publish
Publish semetrika to the npm registry, serve via
cdn.jsdelivr.net/npm/.... Standard pattern, semver ranges, dist-tag-based
prerelease channels.
Rejected. Semetrika is a static-asset library, not a JavaScript dependency - consumers do not call into it, they include its files. An npm package adds publish ceremony (token management, version bumps, dist-tag policy) with no upside over GH-mode for this use case.
Dedicated dist branch
Force-push a dist branch from CI with built files. jsDelivr serves
cdn.jsdelivr.net/gh/drevops/semetrika@dist/semetrika.min.css for "latest from
main" without polluting main's history with build artifacts.
Rejected. The tag boundary is the contract consumers pin to. A dist
branch decouples the URL from the tag, which loses the byte-stability that
makes tag pinning useful in the first place.
Self-hosted CDN
Host dist/ on cdn.drevops.com or similar. Maximum control.
Rejected. We would own the infrastructure, cache invalidation, HTTPS certs, and uptime. No upside over jsDelivr.
Renaming
The semetrika name is not published anywhere consumers depend on -
no npm registry record, no immutable tag commitment. Renaming costs:
- Update
package.json#nameandpackage.json#repository. - Update
docs/content/. - Update any consumer documentation that hard-codes the old GitHub path.
That is the full impact. No npm deprecate, no semver loss, no download
stat reset.