Storybook logging

This document explains how to capture Storybook output to disk for easier debugging and reviews.

Where logs go

Logs are written to logs/storybook/.

• Default interactive dev log: logs/storybook/storybook.log
• Debug variant: logs/storybook/debug-storybook.log
• Build log: logs/storybook/build-storybook.log
• Dated logs: logs/storybook/2026-01-02_12-00-00-storybook.log (ISO date/time)

Note: the logs/ directory is ignored by git (see .gitignore).

NPM scripts

We've added convenience scripts to package.json:

• npm run storybook — unchanged, starts Storybook interactively (no log redirection)
• npm run storybook:log — starts Storybook interactively (uses a pty via script when available) and writes stdout/stderr to logs/storybook/storybook.log (colors stripped by default)
• npm run storybook:debug-log — starts Storybook with a pty and writes to logs/storybook/debug-storybook.log (preserves ANSI colors)
• npm run storybook:dated-log — starts Storybook interactively and writes to a timestamped log file (colors stripped by default)
• npm run build-storybook:log — runs a build and writes output to logs/storybook/build-storybook.log (colors stripped)
• npm run storybook:tail — tails the default storybook.log file

Notes on behavior:

• The log scripts use the script utility to allocate a pseudo-TTY so Storybook prompts (e.g., "run on port 6007 instead?") are answerable while the session is captured.
• By default, color output is removed to avoid ANSI escape sequences in logs (use --debug or --preserve-color flags to keep colors).
• If script is not available on the host, the scripts fall back to a non-PTY capture with a warning; in that case prompts may not be answerable.
• Windows does not always include script; see notes below for cross-platform options.

Helper script

A helper script is available at scripts/start-storybook-logs.sh which accepts the flags:

• --debug (preserve colors)
• --preserve-color (alias for --debug)
• --dated
• --file <name>

Examples:

# start and write to the debug file (preserve ANSI colors)
./scripts/start-storybook-logs.sh --debug

# start and write to a date-stamped file (colors stripped)
./scripts/start-storybook-logs.sh --dated

# explicitly preserve colors when writing to a file
./scripts/start-storybook-logs.sh --preserve-color --file my-run.log

# start Storybook interactively (you can answer prompts) and capture the terminal session to a log (requires `script`)
./scripts/start-storybook-logs.sh --interactive

# interactive with dated file
./scripts/start-storybook-logs.sh --interactive --dated

Notes:

• The --interactive flag uses the script utility to give Storybook a pseudo-tty so interactive prompts (like "run on port 6007 instead?") will work while the session is captured to a log file.
• If script is not available, the helper will exit with an error telling you how to install it.

Choosing dated vs single-file logs

• Use storybook:dated-log (or --dated) when you want a separate file per run for historical inspection.
• Use storybook:log for a single consolidated log file that's easy to tail.