Installation

Node, the package, and a Chromium binary.

Requirements

Node.js 22 or later. Domotion is published as ESM and uses node:-prefix imports throughout.
Playwright's Chromium browser. Domotion captures via Playwright; you install the browser binary separately so the package itself stays small.
macOS for full font fidelity (path / font modes only). The bundled font lookup table targets Apple system fonts. On Linux and Windows, captured text still renders, but path-mode glyphs fall back to SVG <text> when no matching system font is found. See Fonts & non-Latin scripts.

Install the package

Most users want the domotion CLI globally:

npm install -g domotion-svg

If you'd rather scope it to a project (and run it via npx domotion), or if you plan to use the JS API too:

# With npm
npm install domotion-svg

# With pnpm
pnpm add domotion

# With yarn
yarn add domotion

Chromium binary

Domotion captures via Playwright's bundled Chromium build (so captures are deterministic across machines). The binary is fetched on first use — when you call launchChromium() from Domotion, or use DemoRecorder, the package detects a missing binary and runs npx playwright install chromium for you.

If you'd rather pre-install (e.g. on CI runners, where the install adds 30–60s to the first job), do it explicitly:

npx playwright install chromium

On Linux servers / containers, also pull the system libraries Chromium depends on:

npx playwright install --with-deps chromium

⚠

If you're calling chromium.launch() directly from @playwright/test instead of going through Domotion's launchChromium(), you bypass the auto-install step — you'll need to run npx playwright install chromium yourself the first time.

Don't npm install playwright separately — Domotion already depends on @playwright/test at a known version. Installing Playwright manually on top of it can lead to two browser versions on disk and confusing capture differences.

Verify

Drop this script in a file and run it with npx tsx verify.ts:

import { captureElementTree, elementTreeToSvg, launchChromium, wrapSvg } from "domotion";

const browser = await launchChromium();
const page = await browser.newPage();
await page.setContent('<div style="padding:20px;color:#fff;background:#0d1117">Hello</div>');

const tree = await captureElementTree(page, "body", { x: 0, y: 0, width: 400, height: 100 });
const svg = wrapSvg(elementTreeToSvg(tree, 400, 100), 400, 100);

console.log(`OK — ${svg.length} bytes`);
await browser.close();

If you see an "OK — N bytes" line, you're set. If you see a Chromium launch error, jump to Troubleshooting.

TypeScript setup

Domotion ships TypeScript types alongside the JavaScript output ("types": "dist/index.d.ts" in the package's package.json). No separate @types/domotion install is needed.

Because Domotion is ESM-only, your project needs "type": "module" in its package.json or you'll need to use a loader like tsx. The examples in this manual assume one or the other.

Project layout suggestion

Most teams end up with a demos/ or marketing-assets/ folder containing one TypeScript file per animation, plus a tiny shared capture.ts helper:

your-app/
├─ demos/
│  ├─ hero.ts             // produces hero.svg
│  ├─ checkout.ts         // produces checkout.svg
│  ├─ shared.ts           // optimizeSvg, common viewport sizes
│  └─ output/             // generated SVGs (committed or built in CI)
├─ src/                   // your real product code
└─ package.json

You can run them ad-hoc (npx tsx demos/hero.ts) or wire them into package.json scripts. See the Quick start for a complete first script.