Skip to content

Installing

Archi edited this page Oct 18, 2026 · 1 revision

Installing

DemoFlow ships as one npm package, demoflow. It contains the CLI, the MCP server, the renderer and its fonts. It needs Node.js 20 or newer, and it fetches Chromium the first time it is needed.

Overview

Part Where it comes from
CLI and MCP server the demoflow npm package (one bundled file, dist/bin/main.js)
Browser Chromium, installed through the pinned Playwright the first time run or record needs it, or ahead of time with demoflow setup
Video encoder ffmpeg on your PATH if it can encode H.264 (libx264), otherwise the bundled ffmpeg-static 5.3.0 binary
Fonts Inter, shipped inside the package (SIL OFL 1.1)

Linux, macOS and Windows are supported. CI checks the packed package on all three, on Node 20.

Note

The published version is 0.1.0. It has validate, run, setup and mcp. The following are on develop and arrive in the next release:

  • demoflow record
  • the press step
  • starting the app from devCommand

How it works

flowchart LR
    A["npx demoflow run"] --> B{"Chromium installed?"}
    B -- no --> C["download once (~250 MB)"]
    B -- yes --> D["run the scenario"]
    C --> D
    D --> E{"ffmpeg on PATH with libx264?"}
    E -- yes --> F["system ffmpeg"]
    E -- no --> G["bundled ffmpeg-static"]
    F --> H["render MP4"]
    G --> H
Loading
  1. Installing the package downloads no browser.
  2. First browser use: when run or record starts and Chromium is missing from where Playwright expects it, the CLI prints Chromium is not installed: downloading it once (~250 MB). It then runs Playwright's own installer, with the progress on stderr.
  3. If that install fails, the command exits with code 3 and suggests demoflow setup to retry.
  4. Choosing FFmpeg for the render:
    • A system ffmpeg counts only if it lists the libx264 encoder. Fedora's ffmpeg-free, for example, does not.
    • Otherwise the renderer uses the binary that ffmpeg-static downloaded when the package was installed.

Using it

Run it without installing:

npx demoflow --version
npx demoflow run demoflow/customers.demo.json

Or install it globally:

npm install -g demoflow
demoflow --help

Install Chromium ahead of time, for example in a CI image:

npx demoflow setup

setup prints Chromium is installed: <path> (already there) or Chromium installed: <path>. It exits 3 if the installer fails.

Register the MCP server with Claude Code:

claude mcp add demoflow -- npx demoflow mcp

Working inside the DemoFlow repository

Warning

Inside the DemoFlow monorepo, npx demoflow resolves to the private workspace package apps/cli, which is also named demoflow, not to the published one. It fails with demoflow: command not found. Run the published CLI from a directory outside the repository (#105).

Settings

Variable Effect
PLAYWRIGHT_BROWSERS_PATH where Chromium is looked for and installed (Playwright's own variable)
DEMOFLOW_HOME where runs are written; see Project Configuration

Uninstalling

  1. Remove the package:

    npm uninstall -g demoflow

    With npx, clear the npx cache instead.

  2. Remove the runs. They live in the artifacts home, which by default is the OS data directory:

    OS Default artifacts home
    Linux $XDG_DATA_HOME/demoflow, else ~/.local/share/demoflow
    macOS ~/Library/Application Support/demoflow
    Windows %LOCALAPPDATA%\demoflow, else ~\AppData\Local\demoflow

    If you set --out, DEMOFLOW_HOME or artifactsDir, the runs are there instead.

  3. Remove the optional global config file:

    • Linux: ~/.config/demoflow/config.json
    • macOS: ~/Library/Application Support/demoflow/config.json
    • Windows: %APPDATA%\demoflow\config.json
  4. Chromium lives in Playwright's browser cache and is shared with other Playwright installs. Remove it only if nothing else uses it.

Limits / what it never does

  • No browser at install time. Installing the package never downloads Chromium (spec 75, Decision 2).
  • Chromium only. It is the only browser a scenario can use today.
  • The bundled FFmpeg can go missing. If the ffmpeg-static install script was blocked, for example by --ignore-scripts, and there is no suitable system ffmpeg, rendering fails with no FFmpeg. check_project in the MCP Server reports this as ffmpeg: missing.
  • Node ≥ 24 is for contributors only. Developing the monorepo itself needs Node ≥ 24 and Bun; see Contributing.

See also

Clone this wiki locally