flave
Search/

← Changelog

Milestone: flave has docs — getting started on Linux, Ubuntu, and Nix flakes

It worked on one NixOS laptop. Now there is a page that takes a collaborator from a clean Ubuntu install to the desktop app open on their screen, a direnv hook that makes the flake automatic, and docs rendered through LFM rather than around it.

FlaveMilestoneOnboardingDocsNixDirenvSplashLFMAstro

Why Care?

A friend wants to work on flave. Until today, the only documentation for building it was a changelog entry that said “Tauri on NixOS, in about an hour” — true, and useless to anyone not on NixOS.

What’s New?

  • Collaborate, a new header entry on the splash, leading to Getting Started tracks per OS. Linux and Nix are written; macOS and Windows are listed as not written yet, so the gap is visible rather than implied.
  • An Ubuntu walkthrough from lsb_release to pnpm app:dev, with a proof command after every install step and a troubleshooting section for the failures that actually happen (missing webkit2gtk-4.1, the blank-window DMA-BUF bug, launching from the wrong directory).
  • .envrc with use flake. With direnv and nix-direnv, cd flave now loads the devshell and cd .. unloads it.
  • Floors, not pins. The flake moves from nodejs_22 to nodejs; the docs state minimums (>= 22.12, >= 10.26, >= 1.77) and every install command fetches the newest release. CI follows: pnpm latest, Node lts/*.
  • The splash now parses with LFM. Docs go through parseMarkdown from @lossless-group/lfm (0.6.0, from JSR) and a walker ported from content-farm’s splash. Callouts reuse the editor’s tone mapping, so a > [!warning] reads the same in both places. Changelog and context-v pages still use Astro’s built-in markdown.
  • Astro 6 → 7, astro-pagefind 1 → 2. Clean build, no warnings, same 20 pages. Note that pnpm dev on Astro 7 detaches: it returns your prompt and keeps serving. pnpm astro dev status | logs | stop manage it.
  • Reading pages finally have margins. Six pages — the Collaborate index, both changelog pages, both context-v pages, and search — used a .container-narrow class that theme.css never defined, so their text ran to the viewport edges. It is now defined (820px), and both containers share a fluid --gutter (20px on a phone, up to 48px wide). Recorded in DESIGN.md §5.

One thing worth knowing

The splash now has its own pnpm-workspace.yaml, so it is its own pnpm root and carries its own allowBuilds (esbuild, sharp). That makes pnpm install --ignore-workspace, which the README and CI used to require, actively harmful: on pnpm >= 10.26 the flag skips the allowlist and the install fails. Both now run plain pnpm install.

What’s honestly not proven

  • The Ubuntu path has not been run on Ubuntu. It is assembled from Tauri’s published prerequisites and this repo’s manifests. The JS half (pnpm install, pnpm test, pnpm prove, editor build) was verified on a clean install; the Rust/WebKit half was not. The first collaborator through it is the test.
  • Nix on non-NixOS is untested. The page says so and gives the GPU-driver workarounds.
  • The two theme.css copies have drifted. splash/ and apps/editor/ were byte-identical; the splash copy now has the container and gutter tokens and the editor copy does not. Harmless (the editor uses neither), but the sync is now a real follow-up rather than a claimed fact.