Installation
SUPPORTED PATH. The local MIT-licensed CLI runs without a Frontguard account. Hosted and marketplace surfaces remain pre-release.
Use Node.js 22 or newer. Install the package that matches the workflow you intend to run: @frontguard/cli for standalone route/Storybook pipelines, or @frontguard/playwright for assertions inside existing Playwright test suites.
CLI
Install @frontguard/cli as a devDependency in your project and install the Playwright Chromium browser binary used for headless rendering:
Screenshot runs install the Playwright browser build that matches @frontguard/cli. GitHub-hosted runner images update browsers on their own, and that drift flaked screenshot tests (https://x.com/karlhorky/status/2082458846031696091).
LINUX vs MACOS. The --with-deps flag installs required shared libraries on Ubuntu/Debian CI runners. On macOS, Playwright prints a benign note and installs the Chromium binary cleanly.
Playwright package
The CLI and Playwright package use different baseline stores and acceptance behavior; do not treat them as interchangeable.
| Package | Primary Use Case | Default Baseline Location | How Baselines Are Updated |
|---|---|---|---|
@frontguard/cli | Standalone multi-route & multi-viewport visual regression runner with HTML workbench, git orphan storage, and plugins. | frontguard-baselines git orphan branch | Explicitly run frontguard update-baselines --confirm-baselines (ordinary runs never overwrite baselines). |
@frontguard/playwright | In-test visualTest(page, name) helper called inside existing @playwright/test spec files. | __visual_baselines__/ directory in your working tree | Creates missing baseline on first run (isNewBaseline: true); update existing baselines with FRONTGUARD_UPDATE=1. |
@frontguard/mcp | Model Context Protocol server for Claude Code, Cursor, and Windsurf: six read tools, plus two write tools only with FRONTGUARD_MCP_WRITES=1. | Reads ./frontguard-report/report.json locally | MCP promotion is refused in local-report mode. A human runs frontguard update-baselines --confirm-baselines. Cloud approveRun is not a production path. |
Prerequisites
- Node.js 22+: Required by the CLI runtime and worker pool.
- Git repository: Required when storing baselines on the
frontguard-baselinesorphan branch. Ensure your working tree is clean before runningfrontguard update-baselines --confirm-baselinesfor the first time. - Playwright Chromium: Installed once per machine or CI cache via
npx -p @frontguard/cli playwright install --with-deps chromium.
Verify with doctor
Run frontguard doctor at any time to verify your Node.js runtime, Playwright browser binaries, frontguard.config.ts syntax, and git repository state:
