Static site SDK overview
Install the static-site plugin to capture a built HTML site with
vizzly static-site <path>.
It:
- discover pages
- serve the build locally
- open a browser
- capture screenshots across your configured viewports
Install
npm install -D @vizzly-testing/cli @vizzly-testing/static-sitenpx playwright-core install chromiumRun it
npm run buildnpx vizzly static-site ./distFor local review:
npx vizzly tdd startnpx vizzly static-site ./distFor cloud builds:
npx vizzly static-site ./distSet VIZZLY_TOKEN for the cloud run.
The command auto-detects local TDD mode from .vizzly/server.json. If no local server is running, it uses apiKey or VIZZLY_TOKEN for cloud upload. If neither is available, it warns and skips screenshots.
Config
Create shared config locally with vizzly init --quick, then add a
staticSite section for values you want to change. The defaults are:
export default { staticSite: { viewports: [ { name: 'default', width: 1920, height: 1080 }, ], browser: { type: 'chromium', headless: true, args: [], }, screenshot: { fullPage: true, omitBackground: false, timeout: 45000, }, include: null, exclude: null, pageDiscovery: { useSitemap: true, sitemapPath: 'sitemap.xml', scanHtml: true, }, },};Omit concurrency to let Vizzly choose a number from your CPU count, or set a
positive integer to override it. screenshot.timeout is the Playwright capture
timeout. Add screenshot.requestTimeout when you need to override the Vizzly
upload/request timeout.
include and exclude accept either a string or an array of globs.
Cloud builds also honor top-level build.*, comparison.*, parallelId, git metadata, and PR metadata from config, flags, and CI environment variables.
Useful CLI flags
npx vizzly static-site ./dist --viewports "mobile:375x667,desktop:1920x1080"npx vizzly static-site ./dist --include "blog/**" --exclude "**/404.html"npx vizzly static-site ./dist --concurrency 5npx vizzly static-site ./dist --browser chromium --browser-args "--disable-gpu"npx vizzly static-site ./dist --headless --no-full-page --request-timeout 60000npx vizzly static-site ./dist --use-sitemap --sitemap-path sitemap.xmlnpx vizzly static-site ./dist --dry-runLower --concurrency if the browser processes use too much memory.
What it uses for page discovery
The plugin can discover pages from:
sitemap.xml- recursive
.htmlscanning
Those results are merged before capture.