Stepshots logoStepshots

Configuration

Set up and customize the stepshots.config.json file

Configuration

The CLI reads its settings from a stepshots.config.json file. Run stepshots init to generate a starter config, then customize it for your app.

Config File Location

The CLI searches for the config file in this order:

  1. Explicit --config path/to/config.json flag
  2. STEPSHOTS_CONFIG environment variable
  3. Walk up from the current directory looking for stepshots.config.json

Config Structure

json
{
  "baseUrl": "https://your-app.com",
  "viewport": {
    "width": 1280,
    "height": 800
  },
  "defaultDelay": 500,
  "tutorials": {
    "tutorial-key": {
      "url": "/start-page",
      "title": "Tutorial Title",
      "description": "Optional description",
      "steps": [
        {
          "action": "click",
          "selector": "button.cta",
          "highlights": [
            {
              "showBorder": true,
              "callout": "Click here to begin",
              "position": "bottom"
            }
          ]
        }
      ]
    }
  }
}

Top-Level Fields

Field Type Default Description
baseUrl string — Base URL of the website to record. Required.
viewport object { width: 1280, height: 800 } Browser viewport dimensions in pixels.
defaultDelay number 500 Default delay between steps in milliseconds.
tutorials object — Map of tutorial key → tutorial config. Required.

Tutorial Fields

Field Type Required Description
url string Yes Starting page path (relative to baseUrl) or absolute URL.
title string Yes Display title for the tutorial.
description string No Optional description shown in the dashboard.
steps array Yes Array of step actions. See Step Actions.

Step Fields

Field Type Required Description
action string Yes Action type: click, type, navigate, scroll, key, hover, wait, select.
selector string Varies CSS selector for the target element. Required for most actions.
text string For type Text to type into the element.
url string For navigate URL to navigate to.
key string For key Key name to press (e.g., "Enter", "Tab").
value string For select Value to select in a dropdown.
delay number No Override delay for this step (ms). Also used by wait.
scrollX number No Horizontal scroll amount in pixels.
scrollY number No Vertical scroll amount in pixels.
highlights array No Recording-time highlight hints.

Highlight Fields

Highlights in the config are hints applied during recording. You can further edit them in the dashboard editor.

Field Type Description
showBorder boolean Whether to add a border around the element.
callout string Callout text to display.
position string Callout position: top, bottom, left, right.
color string Border/callout color (hex).
icon string Icon type: click, type, scroll, hover, navigate, wait, select, key.
Navigation