# Add shotlist to a project

This guide installs shotlist into an application you already have. If you would rather learn on a prepared project first, start with [Your first screenshot](/docs/tutorials/first-screenshot/), which downloads one.

You need Node.js 20 or later, and a `package.json`.

## Step 1: install the packages

```
npm i -D shotlist playwright
```

```
pnpm add -D shotlist playwright
```

```
yarn add -D shotlist playwright
```

Playwright 1.48 or later is a separate install because its own install step downloads browser binaries. shotlist needs a browser whenever it writes an image, including for `--check`. See [Why Playwright is a peer dependency](/docs/explanation/playwright/) for which commands run without one.

## Step 2: scaffold the configuration

```
npx shotlist --init
```

This writes two commented files, and overwrites neither if they already exist:

```
shotlist.config.yaml
screenshots/recipes/example.yaml
```

## Step 3: point it at your application

Edit `shotlist.config.yaml`. Two things matter to begin with: where the application runs, and where its screenshots belong.

shotlist.config.yaml

```
site:
  url: http://localhost:3000
  serve: npm run dev

install:
  docs: docs/images
```

Every path in the configuration resolves from the file's own folder, not from wherever you run the command. `site.serve` is optional — leave it out if something is always running already. See [Start the site automatically](/docs/how-to/start-the-site/).

## Step 4: verify the install

```
npx shotlist
```

With no arguments, shotlist lists the recipes it found and opens no browser. If it prints the scaffolded `example` recipe, the install is working.

## Set up editor completion

The package ships JSON Schemas generated from the same definitions that validate a run. Point a recipe at one and your editor completes and checks the keys as you type:

screenshots/recipes/order-row.yaml

```
# yaml-language-server: $schema=../../node_modules/shotlist/dist/recipe.schema.json
```

`dist/config.schema.json` describes the configuration and `dist/macro.schema.json` describes a macro. The scaffolded recipe already carries the line.

## Set up agent support

A skill for coding agents ships with the package. It covers what reference cannot: choosing a query that survives a redesign, which side of a mark a label belongs on, and what each error means.

```
mkdir -p .claude/skills
cp -R node_modules/shotlist/skills/shotlist .claude/skills/
```

It is Markdown with YAML frontmatter and nothing else, so any agent that reads instruction files can use it — point yours at `node_modules/shotlist/skills/shotlist/SKILL.md`.

## Related

- [Your first screenshot](/docs/tutorials/first-screenshot/)
- [Configuration reference](/docs/reference/configuration/)
- [Run shotlist in CI](/docs/how-to/run-in-ci/)

Written by Nicola Mustone · Applies to shotlist 0.6.0 · Maintained by Nicola Mustone

Published date unavailable · Updated date unavailable · [View source](https://github.com/SirDarcanos/shotlist.dev/blob/main/src/pages/docs/how-to/install.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/how-to/install.astro)