Skip to content
Latest

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

Terminal window
npm install -D @vizzly-testing/cli @vizzly-testing/static-site
npx playwright-core install chromium

Run it

Terminal window
npm run build
npx vizzly static-site ./dist

For local review:

Terminal window
npx vizzly tdd start
npx vizzly static-site ./dist

For cloud builds:

Terminal window
npx vizzly static-site ./dist

Set 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

Terminal window
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 5
npx vizzly static-site ./dist --browser chromium --browser-args "--disable-gpu"
npx vizzly static-site ./dist --headless --no-full-page --request-timeout 60000
npx vizzly static-site ./dist --use-sitemap --sitemap-path sitemap.xml
npx vizzly static-site ./dist --dry-run

Lower --concurrency if the browser processes use too much memory.

What it uses for page discovery

The plugin can discover pages from:

  • sitemap.xml
  • recursive .html scanning

Those results are merged before capture.

Next steps