# Why Playwright is a peer dependency

shotlist needs a browser to take a screenshot, but it does not depend on Playwright directly. You install Playwright 1.48 or later alongside shotlist, because request-level WebSocket routing is what lets the Run enforce network destinations. This page explains why the dependency remains optional, and what follows from it.

## The cost of installing a browser

Playwright's install step downloads browser binaries — hundreds of megabytes, on every machine that runs `npm install`. If shotlist depended on Playwright in the ordinary way, every project that depends on shotlist would pay that cost, including projects that never take a screenshot on that machine.

Several common situations get nothing at all for it:

- a continuous integration job that installs dependencies to run unit tests
- a machine that only reads or lints the recipes
- a developer who never runs the screenshot step locally

Making it a peer dependency moves that decision to the project. You install a browser when you intend to use one.

## Which commands need a browser

The rule is simple: anything that writes an image needs one. That includes `--check`, and it includes `source: file` recipes, which drive no site but still draw their callouts in a browser page.

Everything that only reads or writes files runs without a browser: `--init`, `--help`, `--version`, `shotlist` with no arguments, which lists the recipes it found, and `--lint`, which parses every file in the project and reports what is wrong with all of them.

[Linting](/docs/how-to/lint/) is the one that earns the distinction. A continuous integration job that only checks the shot list is valid needs neither Playwright nor a running site, so it can skip both and finish in about a second.

## How the browser is found

A run that needs a browser looks in three places, in order:

1. `playwright`
2. `playwright-core`
3. the `npx` cache

The third is what lets `npx shotlist` work in a project that has installed neither, which is useful when you are trying the tool rather than adopting it.

Finding none of them, it stops before opening anything, and prints the command that fixes it:

```
Playwright is not installed. shotlist does not install it, because its
postinstall downloads browsers. Install it with:
  npm i -D playwright
```

## Why the failure arrives first

The browser is the first thing a run reaches for, before any recipe is taken. A missing browser is therefore a failure that happens before any work, rather than partway through: nothing is written, and nothing is left half-finished.

This matters more than it sounds. A run that fails partway through `--install` leaves a documentation folder holding some new images and some old ones, and no record of which is which.

## Related

- [Your first screenshot](/docs/tutorials/first-screenshot/)
- [Run shotlist in CI](/docs/how-to/run-in-ci/)
- [Why screenshots drift](/docs/explanation/image-drift/)

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/explanation/playwright.astro) · [Propose a correction](https://github.com/SirDarcanos/shotlist.dev/edit/main/src/pages/docs/explanation/playwright.astro)