Chromium setup

Viewing, authoring, and live-presenting a deck need only a normal browser. A few build-time features render slides headlessly, and those need a real Chromium binary. Chromium is optional: if you never use those features, you never need it.

What needs Chromium

Feature	Command / API	Without Chromium
Slide thumbnails (overview grid)	liebstoeckel build, liebstoeckel live, buildDeck()	Skips the capture and keeps building. The deck works; the overview grid falls back to a live render.
Regenerate thumbnails	liebstoeckel thumbs	Fails with an error.
Export to PNG or PDF	liebstoeckel export	Fails with an error.

The split is deliberate. build and live treat thumbnails as a best-effort enhancement, so a missing browser never blocks a build. thumbs and export exist only to produce that output, so they fail loudly instead of writing nothing.

Check what you have

liebstoeckel doctor reports your build environment (Bun version, whether a Chromium was found, and where its path is recorded):

liebstoeckel doctor            # human summary; --json for the machine-readable form

If a Chrome or Chromium is already on the machine, liebstoeckel usually finds it on its own (see Resolution order), you may not need to do anything.

Provide a Chromium

If doctor reports none, any of these works.

Let liebstoeckel install and remember Playwright’s Chromium for you:

liebstoeckel doctor --install-chromium     # installs, then records the path in your config

Or install it yourself (liebstoeckel ships playwright-core, which has no browser of its own):

bunx playwright install chromium

Or point LIEBSTOECKEL_CHROMIUM at a Chrome or Chromium you already have:

export LIEBSTOECKEL_CHROMIUM=/usr/bin/chromium       # or a full path to Chrome
liebstoeckel build my-talk

Use full Chromium, not chrome-headless-shell

Point LIEBSTOECKEL_CHROMIUM at a complete Chrome or Chromium build. The lighter chrome-headless-shell can crash (SIGSEGV) in some sandboxes, so capture uses full Chromium.

Resolution order

When a feature needs a browser, liebstoeckel looks in this order and uses the first binary that exists on disk:

1. An explicit executablePath passed to the thumbnails/export API.
2. The LIEBSTOECKEL_CHROMIUM environment variable — including the path doctor records in your config (~/.config/liebstoeckel/config.json), which the CLI loads into this variable when you haven’t set it yourself.
3. A system Chrome/Chromium: PUPPETEER_EXECUTABLE_PATH / CHROME_PATH, Puppeteer’s install cache, google-chrome / chromium / chromium-browser on PATH, and the standard macOS/Windows install locations.
4. The Chromium installed by Playwright.

The existence check matters: Playwright reports a computed path even when nothing is installed, so liebstoeckel verifies the file is really there before trusting it. This keeps the “no Chromium” path honest in CI.

Containers and CI

Capture launches Chromium with container-friendly flags so it runs without a GPU or user namespace:

--no-sandbox --disable-gpu --disable-dev-shm-usage --single-process --no-zygote

In a container image, either run bunx playwright install chromium during the build, or install your distro’s Chromium package and set LIEBSTOECKEL_CHROMIUM to it.

When no Chromium is found

The “no Chromium found” message is expected if you never installed one. What follows depends on the command:

• liebstoeckel build and liebstoeckel live log a note that thumbnails were skipped and finish normally. Run liebstoeckel doctor --install-chromium (or provide a browser as above) to get the overview thumbnails back.
• liebstoeckel thumbs and liebstoeckel export stop with an error that names the fixes (liebstoeckel doctor --install-chromium, or set LIEBSTOECKEL_CHROMIUM).

Skip thumbnails on purpose

To build without thumbnails even when a browser is present, set LIEBSTOECKEL_NO_THUMBS:

LIEBSTOECKEL_NO_THUMBS=1 liebstoeckel build my-talk

Thumbnails How build-time slide thumbnails are captured and embedded.

Building & deploying The single-file build and what ends up in it.