Skip to main content

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:

ChannelURL shapeUse case
jsDelivr CDNhttps://cdn.jsdelivr.net/gh/drevops/semetrika@TAG/dist/semetrika.min.cssDrop-in <link> / <script>, no install
Bundler installnpm install github:drevops/semetrika#TAGVite, webpack, other build pipelines
Release-asset downloadhttps://github.com/drevops/semetrika/releases/download/TAG/semetrika.min.cssSelf-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 to dist/.

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:

FileContents
semetrika.css / .min.css / .min.css.mapFull combined bundle: layers + variables + options + framework + foundation + utilities + components
semetrika-variables.css / .min.css / .min.css.mapTokens only: layers + variables + options. Reference file - see below.
semetrika.js / .min.js / .min.js.mapBundled utilities + component JS (IIFE, external @floating-ui/dom inlined)
icons.svgIcon sprite (one <symbol> per icon, holding one or both of its variant artworks)
fonts/<typeface>/<face>.woff2The 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:

  1. Checks out the tagged commit.
  2. Installs dependencies (yarn install --frozen-lockfile).
  3. Builds (yarn build).
  4. Attaches every file under dist/ to the GitHub release via softprops/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 a prepare script that builds on install), the consumer ends up with no bundle in node_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 does yarn build, then git 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 prepare script - package.json runs yarn build on 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#name and package.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.