Config Reference

A stepbook project is anchored by a config file in its root. Three filenames are recognized: stepbook.config.json, stepbook.config.mjs, and stepbook.config.js.

Minimal config

{
  "name": "demo",
  "steps": ["steps/**/*.step.ts"],
  "pipelineFile": "pipeline.ts"
}

A config must set steps, pipelineFile, or both. If it sets neither, stepbook errors at load time.

Fields

Field	Type	Description
name	string	Pipeline name. Required when there's no pipelineFile (where it would come from definePipeline). Used in run blobs, snapshot dirs, and the UI label.
steps	string | string[]	Glob pattern(s) for unit files (*.step.ts). Discovered units are composed by the entrypoint.
pipelineFile	string	Path to pipeline.ts — the entrypoint definePipeline({ name, runner }) that stepbook run executes. Also carries lifecycle hooks + side-effect imports.
editor	EditorKind	External editor opened by source-link buttons in the dashboard. Default vscode.
canonicalInput	string	Filename inside inputs/ used for ▶ Run when no input is given. Default: the first file in inputs/.

EditorKind is one of vscode | cursor | subl | webstorm | idea.

Units and the entrypoint

Stepbook learns about your pipeline in two parts:

Units — glob discovery. Set steps to a glob. Every matching file whose default export is a defineStep({...}) is discovered as a unit. Non-unit files are skipped.

{ "name": "demo", "steps": ["steps/**/*.step.ts"] }

The entrypoint — pipelineFile. Point pipelineFile at a pipeline.ts that default-exports definePipeline({ name, runner }). stepbook run executes that runner, which composes the discovered units by calling them (see the Step-Author API). The pipeline.ts is also where project-level beforeAll/afterAll hooks and any side-effect imports live.

{ "name": "demo", "steps": ["steps/**/*.step.ts"], "pipelineFile": "pipeline.ts" }

Computed config (.mjs / .js)

When you need to compute values, use the .mjs or .js form and default-export the config object:

// stepbook.config.mjs
export default {
  name: 'my-pipeline',
  steps: ['steps/**/*.step.ts'],
  editor: process.env.EDITOR_KIND ?? 'vscode',
}

Discovery

When you run a command, stepbook locates the config with this precedence:

1. STEPBOOK_CONFIG env var — an explicit path. If it points at a missing file, stepbook errors.
2. cwd walk-up — looks for stepbook.config.{json,mjs,js} in the current directory and its ancestors, stopping at the filesystem root or after 6 hops.
3. fallback — tooling may supply a fallback (the dashboard uses examples/demo when launched from the workspace root). Not used by the CLI in a normal project.

# Point at a specific config explicitly:
STEPBOOK_CONFIG=/path/to/stepbook.config.json stepbook run

Derived paths

From the config, stepbook derives the paths the runner uses. You don't set these — they're computed:

Derived	How it's computed
projectDir	Directory containing the config file. Used as the glob base.
stateDir	<projectDir>/state (or <dirname(pipelineFile)>/state when pipelineFile is set).
stepGlobs	steps normalized to an array, resolved relative to the config dir.
pipelineFile	Absolute path, if set.

Everything stepbook persists — runs, cache, snapshots, reports — lives under stateDir. Gitignore it. See Project Structure.