Skip to main content
JUMP TO:Quick StartCLI CommandsConfigurationPlaywright APIMCP ServerGitHub Actions
Getting started / Installation(2 of 37)

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.

Setup and Environment Diagnostics — Node 22+, Playwright Chromium, Doctor Checks and Clean Git Tree
FIG 01 · SETUP & ENVIRONMENT DIAGNOSTICS — NODE 22+, PLAYWRIGHT CHROMIUM, DOCTOR CHECKS & CLEAN GIT TREE

CLI

Install @frontguard/cli as a devDependency in your project and install the Playwright Chromium browser binary used for headless rendering:

terminal
$ npm install -D @frontguard/cli
$ npm install -D @frontguard/playwright
$ npx -p @frontguard/cli playwright install --with-deps chromium
$ npx -p @frontguard/cli frontguard doctor

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.

PackagePrimary Use CaseDefault Baseline LocationHow Baselines Are Updated
@frontguard/cliStandalone multi-route & multi-viewport visual regression runner with HTML workbench, git orphan storage, and plugins.frontguard-baselines git orphan branchExplicitly run frontguard update-baselines --confirm-baselines (ordinary runs never overwrite baselines).
@frontguard/playwrightIn-test visualTest(page, name) helper called inside existing @playwright/test spec files.__visual_baselines__/ directory in your working treeCreates missing baseline on first run (isNewBaseline: true); update existing baselines with FRONTGUARD_UPDATE=1.
@frontguard/mcpModel 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 locallyMCP 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-baselines orphan branch. Ensure your working tree is clean before running frontguard update-baselines --confirm-baselines for 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:

terminal
$ npx -p @frontguard/cli frontguard doctor

  frontguard doctor
  ✓ Node.js v22.x (>= 22.0.0)
  ✓ Playwright Chromium installed
  ✓ Config valid (frontguard.config.ts)
  ✓ Git repository clean (origin remote configured)