build-and-distribution

name

build-and-distribution

description

How r3 is built and shipped — the single-file Bun.build --compile binary and its browser-target Tailwind CSS pre-pass, the two release channels (GitHub Releases + the npm launcher with per-platform optional-dependency packages), the `bun` → empty-npm-package override, and the frontend-only browser demo deployed to GitHub Pages. Use when touching scripts/ (compile, spa-css, release-binaries, stage-npm-packages, build-demo, stage-pages, gen-demo-fixtures), npm/, web/demo/, bunfig.toml, the nix build, the Pages or release workflows, or debugging a broken binary/demo build.

Building and shipping r3

This file is the design source of truth for r3's build + distribution — update it here when the pipeline changes. (Cutting an actual release — changelog, version bump, tag — is the separate release skill.)

The single-file binary

bun run build runs one Bun.build({ compile }) (scripts/compile.ts) over the CLI entry — which imports the daemon, which imports the SPA via import index from "../web/index.html". That embeds the Bun runtime, all JS deps, bun:sqlite, and the bundled SPA (as Bun.embeddedFiles) into one ./r3 executable that serves its own UI. The CLI is the binary; the hidden __daemon subcommand re-execs it to serve.

The CSS pre-pass is load-bearing. The SPA stylesheet is Tailwind-compiled first in a separate browser-target pass (scripts/spa-css.ts, shared with release-binaries.ts). A compile build is target:"bun", whose CSS printer keeps Tailwind's native nesting verbatim — and un-lowered nesting breaks in browsers (& {…} under ::placeholder is unmatchable, so placeholders lose their dimming). The pre-pass lowers it flat; the compile build embeds it as-is. Don't remove it.

Two release channels, one tag-driven pipeline

scripts/release-binaries.ts cross-compiles the four r3-<os>-<arch> binaries. From there:

• GitHub Releases carry the raw assets (curl / Homebrew). No checksum manifest ships with them — GitHub publishes a sha256 digest per asset, and the release job verifies against those digests on the reuse path.
• npm ships a tiny launcher (@hyperlogue/r3, npm/launch.mjs) whose per-platform binaries are optional-dependency packages (@hyperlogue/r3-<os>-<arch>, staged by scripts/stage-npm-packages.ts). npm installs only the matching package, so bunx/npx @hyperlogue/r3@x.y.z resolves-and-execs that version's binary with no runtime download — the launcher only does createRequire().resolve + spawn.

npm auth is trusted publishing (OIDC) — there is no npm token. Each of the five packages registers release.yml by filename as its trusted publisher on npmjs.com, and npm mints a short-lived publish-only credential from the runner's OIDC identity. So: renaming .github/workflows/release.yml breaks publishing until all five registrations are updated, publishing can't move to another workflow or a self-hosted runner, and a brand-new package name (adding a platform target) has no trusted publisher yet — its first publish is manual, then register release.yml on it. Requires npm ≥ 11.5.1, which is why the job upgrades npm and omits setup-node's registry-url (its .npmrc placeholder token would shadow OIDC).

package.json overrides bun → empty-npm-package

bun-plugin-tailwind peer-depends on the bun npm package, which would pull Oven's wrapper + 16 platform binaries into bun.lock (and thus bun.nix and the nix build's fetch set), and whose broken bin shim shadows bun on install-script PATHs. The override pins that name to an empty stub.

The plugin has no public source repo — report issues to oven-sh/bun, and drop the override if a release marks the peer optional or moves it to engines.

The frontend-only demo → GitHub Pages

bun run build:demo (scripts/build-demo.ts) produces a static dist/demo/ that runs the whole SPA with no daemon — a third client of the same components, but its "backend" is an in-browser store (web/demo/) over localStorage.

It is the same web/index.html Bun.build, with:

• one onResolve plugin aliasing web/src/{api.ts,demo-chrome.tsx,main.css} to their web/demo/ counterparts — so every fetch/SSE call hits the browser backend, the demo chrome replaces its production stub, and Tailwind also scans web/demo;
• an EventSource shim.

The demo reuses the server's genuinely pure modules verbatim (anchor.ts, textdiff.ts, prompt.ts, shared/types.ts) and pre-bakes all Shiki/markdown HTML at build time (scripts/gen-demo-fixtures.ts → web/demo/fixtures.gen.ts), so no highlighter, sqlite, or git ships to the browser. Re-bake with bun run gen:demo only after editing canned content.

The seed dogfoods r3 on its own code; a scripted agent watches each review and closes the submit→reply→round loop. Reviews can't be created in the demo (no git) — it's a read-and-respond tour of the seeded reviews. Daemon-only affordances are gated by a build-time flag the aliased api.ts exports rather than by a demo check inside the component: CAN_MANAGE_TOKENS is false there, so SettingsPopup drops its whole "Access" (login tokens) section — nothing beyond this tab is reachable, so remote-access tokens have no meaning and a control that could only fail is worse than none.

The demo must never fork the contract: it implements shared/types.ts, it doesn't extend it.

The Pages layout

.github/workflows/pages.yml builds the demo and deploys on push to main, mounting it at …/r3/demo/ — the project page (/r3/, the repo name, forced by Pages) plus a /demo sub-path.

R3_DEMO_BASE=<base_path>/demo (base_path from configure-pages) bakes that prefix into the router (hrefFor/__R3_BASE__) and asset publicPath. Then scripts/stage-pages.ts lays out dist/pages:

• the build under demo/,
• a root→demo redirect,
• and — because Pages honors only a single site-root 404.html (subdirectory ones are ignored) — the SPA copied to the site-root 404.html, so a deep-link reload of /r3/demo/review_x still boots it (its asset URLs are absolute).

Local build:demo defaults to a root base, so bunx serve -s dist/demo just works.

Nix

nix/r3.nix drives the same bun run build with a custom buildPhase on top of stdenv + the bun2nix hook (which installs the pinned deps from bun.nix) — the compile step is more than bun2nix's default module→binary path. bun.nix is generated from bun.lock and committed: any dependency change must regenerate it in the same commit.

Heritage

v1 was one server per repo with a gitignored per-repo .r3/review.sqlite; v2 replaced it with the one per-user daemon + global store. Some code comments still cite the old model as history.