Getting started

Set it up with Claude Code (fastest)

pro-visu ships a Claude Code plugin so an AI agent can install it and write the config for you. In Claude Code, add the marketplace and install the plugin:

/plugin marketplace add pro-laico/pro-visu
/plugin install pro-visu@prolaico

Then just ask — e.g. "set up pro-visu for this project and capture the homepage." The skill installs the CLI, scaffolds pro-visu.config.ts, picks generators, points them at your site (or a managed server), and runs the generate for you.

Prefer to wire it up by hand? The rest of this page is the manual path.

Install

Two ways to run it — same CLI, same generators; they differ only in how you install it and author config:

A TS pro-visu.config.ts needs the dev dependency because it does import { defineConfig } from "pro-visu", which has to resolve from your project's node_modules (both to type-check and to run). A JSON config has no import, so it works in any mode — and pro-visu init --json generates a pro-visu.schema.json that gives editors the same autocomplete, validation, and hover docs.

A — As a project dev-dependency (recommended):

pnpm add -D pro-visu

Gives you the typed defineConfig authoring experience and pins the version in your lockfile, so you — and CI — generate byte-identical assets.

B — Without installing (npx or global):

npx pro-visu init --json     # dependency-free JSON config + JSON Schema
npx pro-visu generate

…or install globally (npm i -g pro-visu). No project dependency; the generated pro-visu.schema.json still gives your editor autocomplete + validation on the JSON config.

Unreleased builds (contributing, or pinning main): install from GitHub (pnpm add -D github:pro-laico/pro-visu), a pnpm link, or a file: path — see the package README for those.

Initialise

npx pro-visu init

init is idempotent and sets up everything needed:

• writes a starter pro-visu.config.ts (unless a config already exists) — or, with --json, a pro-visu.config.json plus a pro-visu.schema.json for editor autocomplete,
• creates the output directory (pro-visu/) and adds it to .gitignore,
• adds a "pro-visu": "pro-visu generate" script to package.json (skip with --no-script),
• downloads the managed Chromium and ensures ffmpeg (skip with --skip-browser).

The first browser download is one-time, cached, and shared across projects.

Configure

Open pro-visu.config.ts and point an asset at your site. The starter looks like this:

import { defineConfig } from "pro-visu";

const URL = "http://localhost:3101";

export default defineConfig({
  settings: {
    outDir: "pro-visu",
    concurrency: 2,
    browser: { headless: true },
    defaults: {
      "scroll-reel": { width: 1440, height: 900, fps: 30 },
    },
  },
  assets: [
    { name: "home-reel", url: URL, generator: "scroll-reel" },
  ],
});

If you scaffolded with --json, the equivalent pro-visu.config.json carries a "$schema": "./pro-visu.schema.json" line — your editor reads it for the same autocomplete and validation. Refresh that schema after upgrading the tool with pro-visu schema.

See Configuration for the full shape, and Generators for every asset type and its options.

Generate

Start your site (or use a deployed URL), then:

npx pro-visu generate

Each asset is rendered into outDir and recorded in manifest.json. Review what was produced with:

npx pro-visu list

Don't want to start the site yourself? Configure a managed server and the CLI will build → start → capture → stop it for you, so pro-visu generate is the only command you run.

Iterate faster

• pro-visu generate --draft — lower fps/scale and a faster encoder for quick previews.
• pro-visu generate --asset home-reel — only (re)build named assets (repeatable).
• pro-visu generate --cache — skip assets whose inputs + options are unchanged.
• pro-visu generate --skip-build — keep the managed server but skip its build step.

See the full CLI reference.

Requirements

• Node.js (the CLI runs on Node).
• Chromium — Playwright's managed build, fetched automatically; or point at your own via settings.browser.channel / executablePath.
• ffmpeg — a working binary is ensured automatically for the video generators.