Skip to content
Documentation

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, which downloads one.

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

Step 1: install the packages

npm i -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 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.

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