Installation
Purpose: add Watcher to an existing Playwright project.
Before you start: confirm the requirements, and open a terminal in the directory that contains your project's package.json.
Install the package
Install Watcher as a development dependency of your project:
npm install --save-dev @elixir-nexus/watcher@alpha
The package is @elixir-nexus/watcher. Its command-line tool is called watcher. An unrelated npm package is named plain watcher; do not install it, and do not run npx watcher before installing the scoped package locally.
Why a project-local install?
Watcher must be installed in the project, not globally. During Playwright-aware runs, Playwright loads Watcher's reporter (@elixir-nexus/watcher/reporter) from your project's node_modules. A global install cannot be resolved from there.
What installation changes
The npm install command you run updates your package.json and lockfile, as any dev dependency does. After that, Watcher itself does not modify your package.json, lockfile, Playwright configuration, tests or .gitignore.
Keep run history out of Git
On its first valid start, Watcher creates a .watcher/ directory in your project root for its local history database. We recommend adding it to your Git ignore rules yourself:
.watcher/
Watcher never edits .gitignore for you.
Verify the installation
npx watcher --version
Expected result: the installed version, for example:
0.1.0-alpha.1
Next step
Follow the Quickstart to start Watcher and complete your first run.
Troubleshooting
| Symptom | Fix |
|---|---|
Watcher requires Node.js ^22.13.0 || >=24.0.0. | Switch to a supported Node.js version. Node 23 is excluded. |
npx watcher runs something unexpected | Install @elixir-nexus/watcher@alpha locally first; plain watcher is a different package. |
More fixes are in Troubleshooting.