Skip to content
Vizzly Docs

Static Site SDK Overview

The static-site package adds a vizzly static-site <path> command through the CLI plugin system.

Point it at a built site and it will:

  • 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
vizzly static-site ./dist

For local review:

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

For cloud builds:

Terminal window
vizzly static-site ./dist

with VIZZLY_TOKEN configured.

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

vizzly init can add the base config for you. With no config, the runtime defaults look like this:

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
vizzly static-site ./dist --viewports "mobile:375x667,desktop:1920x1080"
vizzly static-site ./dist --include "blog/**" --exclude "**/404.html"
vizzly static-site ./dist --concurrency 5
vizzly static-site ./dist --browser chromium --browser-args "--disable-gpu"
vizzly static-site ./dist --headless --no-full-page --request-timeout 60000
vizzly static-site ./dist --use-sitemap --sitemap-path sitemap.xml
vizzly static-site ./dist --dry-run

The default concurrency is chosen dynamically from your CPU count, so treat the config value as something you can tune rather than a fixed platform constant.

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