Quickstart

Follow these steps to set up Cappa inside an existing frontend project.

1. Install dependencies

Cappa is distributed as a set of packages. Install the CLI alongside the core runtime with your preferred package manager:

pnpm add -D @cappa/cli @cappa/core

Cappa delegates browser automation to Playwright. Install the Playwright browsers if your project has not already done so:

pnpm add -D playwright

To be able to capture screenshots, you need also playwright browsers installed for your system.

2. Create a configuration file

Create a cappa.config.ts file in the root of your project and define where screenshots should be saved:

import { defineConfig } from '@cappa/core';

export default defineConfig({
  outputDir: 'screenshots'
});

Configuration objects can include additional options like custom commands, plugin settings, and CI integration hooks. Explore the Configuration guide for a deeper tour.

3. Add a plugin

Cappa needs to be able to know where to take screenshots from. It ships with a plugin system so you can connect Storybook or other custom data sources without forking the core tool.

import { defineConfig } from '@cappa/core';
import { cappaPluginStorybook } from '@cappa/plugin-storybook';

export default defineConfig({
  plugins: [cappaPluginStorybook({ storybookUrl: 'http://localhost:6006' })],
});

This is just an example. For a full guide on how to use the Storybook plugin, see the Storybook integration guide.

4. Capture, review, and approve

With the configuration in place you can run the standard workflow:

# capture screenshots with Playwright
cappa capture

# review diffs in an interactive UI
cappa review

# approve changes and update baselines
cappa approve

The CLI keeps track of the working directory so you can review screenshots locally or as part of a continuous integration job.