Skip to content
Vizzly Docs

Configuration

Put shared settings in vizzly.config.js. Use environment variables or command flags when one run needs different values.

Start with vizzly init

Run setup locally:

Terminal window
npx vizzly init

The wizard creates config and offers agent guidance and cloud linking. To create only the config, use npx vizzly init --quick. Commit it before running in CI.

To add the Vizzly skill and an AGENTS.md note during first-time setup:

Terminal window
npx vizzly init --agent-guidance

Use --agent-skill for only the skill. Init leaves an existing setup alone, including its agent files. Edit config directly to change settings; --force explicitly replaces the selected config. In package.json, it replaces only the vizzly property.

Example config

You only need to include values you want to change:

export default {
  upload: { batchSize: 20 },
  // Uncomment to override comparison settings:
  // comparison: { threshold: 2, minClusterSize: 2 },
};

Vizzly also loads vizzly.config.ts, rc files, and vizzly settings in package.json. Use --config <path> to select a file.

Node loads TypeScript config without a separate compiler. Use import type for type-only imports and include extensions in local imports. Enums, runtime namespaces, constructor parameter properties, and tsconfig.json path aliases aren’t supported in config or its imports.

What matters most

server

  • server.port: local screenshot-server port.
  • server.timeout: server timeout in milliseconds.

build

Use build.name, build.environment, build.branch, build.commit, and build.message for shared build metadata.

upload

  • upload.screenshotsDir: screenshot directory for tools that read this setting.
  • upload.batchSize: screenshots sent per batch.
  • upload.timeout: time to wait for build processing, in milliseconds.

The upload command still takes a directory argument. Its --upload-timeout flag changes the processing wait, not the HTTP upload timeout.

comparison

Set comparison.threshold for color tolerance and comparison.minClusterSize for the smallest changed pixel group to count.

Local comparisons default to 2 for both. Cloud comparisons use the project’s settings unless you override them in config, environment variables, or flags. Leaving these fields out preserves the cloud project’s settings.

tdd

Use tdd start --open to open the dashboard, or tdd run --no-open to keep the static report closed. See TDD mode.

Other supported top-level fields

  • project: organization and project slugs saved by vizzly project link.
  • apiKey, apiUrl: API credential and server URL. Prefer VIZZLY_TOKEN over saving a credential in config.
  • signatureProperties: custom metadata keys used for local baseline matching.
  • plugins: plugin package names to load.
  • parallelId: shared ID for parallel test shards.
  • baselineBuildId, baselineComparisonId: cloud baselines for local runs.
  • eager, wait, allowNoToken: run options.

Environment variables

The config loader reads:

  • VIZZLY_TOKEN
  • VIZZLY_API_URL
  • VIZZLY_BUILD_NAME
  • VIZZLY_PARALLEL_ID
  • VIZZLY_THRESHOLD
  • VIZZLY_MIN_CLUSTER_SIZE

Use VIZZLY_LOG_LEVEL for output and VIZZLY_HOME for the user-state directory. Set the screenshot-server port with server.port or --port.

In CI, VIZZLY_COMMIT_SHA, VIZZLY_COMMIT_MESSAGE, and VIZZLY_BRANCH override Git metadata. vizzly config --json shows the loaded config and any linked project.

Precedence

Highest to lowest:

  1. command flags
  2. environment variables
  3. config file
  4. built-in defaults

Next steps