Managed server

When settings.server is set, pro-visu generate builds your site (if a build is given), starts it, waits for it to respond, runs the capture, then shuts it down — so a project's npm script can be just pro-visu generate.

import { defineConfig } from "pro-visu";

export default defineConfig({
  settings: {
    server: {
      build: "next build",
      command: "next start", // PORT is injected (defaults to 3101) — no -p needed
    },
  },
  assets: [
    // url omitted → captures the server root; relative paths resolve against it
    { name: "home", generator: "scroll-reel" },
    { name: "pricing", url: "/pricing", generator: "scroll-reel" },
  ],
});

The managed server's URL is the default base for capture targets: a url-based asset that omits url captures the server root, and any relative url or routes entry (e.g. /pricing) resolves against it. Absolute URLs pass through unchanged.

Fields

Field	Type	Default	Meaning
`command`	`string`	—	Required. Command that starts the server, run via the shell. The tool sets `PORT`/`HOST` in its environment to the readiness port/host, so frameworks that honour `PORT` (Next, Vite, …) bind it automatically — `"next start"` is enough. An explicit flag (e.g. `next start -p 4000`) still wins.
`build`	`string`	—	Optional one-shot build to run first, e.g. `"next build"`.
`url`	`string`	—	Health-check URL polled until it responds. Defaults to `http://127.0.0.1:<port>`.
`port`	`number`	`3101`	Port the readiness check probes (and derives `url` from), also passed to the command as `PORT` so it binds the same port.
`cwd`	`string`	config dir	Working directory for `build` + `command`, relative to the config.
`readyTimeoutMs`	`number`	`120000`	Max time to wait for the server to become reachable.
`reuseExisting`	`boolean`	`true`	If a server is already reachable at the URL, use it as-is (don't start or stop one).

Set a custom port (or url) only if your server can't read PORT from the environment, or you need a non-default port. Otherwise leave both off — the tool keeps the command, the readiness check, and your asset URLs in sync for you.

Lifecycle and flags

A normal run is: build → start → wait for ready → capture all assets → stop.

The server is skipped automatically when nothing in the selection needs a URL — i.e. every selected asset is a local generator (wall, image, palette, specimen, palette-reel). So a wall in test mode, or pro-visu generate <a local asset>, renders without paying for a site build/boot it never uses. (A real wall still pulls in its URL-based tile producers, so the server starts for it.)

Two flags adjust the lifecycle explicitly:

--skip-server — don't manage a server at all; capture an already-running site at the asset URLs. Pair this with a deployed URL or a dev server you started yourself. (Without a managed server there's no base URL, so assets need absolute urls.)
--skip-build — keep the managed server but drop its build step, for fast iteration when the site itself is unchanged.

If a run is killed hard before teardown, pro-visu reset stops any orphaned server process tree and cleans up temp directories.

Fields

Lifecycle and flags

On this page