storybook-startup-benchmark

name	storybook-startup-benchmark
description	Measure Storybook startup time from spawning `storybook dev` until the first story renders in the browser. Use when the user asks about Storybook boot time, server-ready timing, first story render timing, startup regressions, benchmarking with repeat runs, or comparing Storybook versions or feature flags.
allowed-tools	Bash, Read

Storybook Startup Benchmark

Purpose

Use this skill to build or explain a repeatable benchmark for Storybook startup:

• server: process spawn -> Storybook server responds
• browser: server responds -> first story rendered
• total: process spawn -> first story rendered

Quick Start

When asked to benchmark Storybook startup:

1. Confirm the boundary:
   • Start timing immediately before spawning storybook dev
   • Open Storybook at /, not iframe.html
   • Stop timing on first story mount plus one requestAnimationFrame()
2. Check whether the repo already has a benchmark script. Reuse it if possible.
3. If not, create a Node script that:
   • starts Storybook with --no-open
   • waits for the server to respond
   • launches a browser it controls
   • waits for a preview-side render signal
   • prints JSON results
4. Add --repeat <count> support with grouped summary stats.

Measurement Rules

Use these defaults unless the user asks otherwise:

• Start URL: /
• Browser path: normal manager page, let Storybook load the preview iframe itself
• Render signal: first preview story mount + one requestAnimationFrame()
• Browser launch: external harness launches the browser, not Storybook
• Auto-open: disable Storybook browser auto-open with storybook dev --no-open

Do not measure only CLI output. Server listening is not the same as first story rendered.

Recommended Implementation

1. Preview-side signal

Add a small global preview decorator or component that runs once on the first story mount:

• wait one requestAnimationFrame()
• set a global value like window.__sbStartupBenchmark
• also mirror that value to window.top when same-origin
• optionally call performance.mark('sb:first-story-rendered')

Preferred payload:

{
  firstStoryRenderedAt: performance.now(),
  storyId: id
}

2. Harness behavior

The benchmark script should:

1. Fail fast if the target Storybook port is already in use
2. Spawn Storybook with --no-open
3. Start timing immediately before spawn
4. Wait for HTTP readiness on the Storybook URL
5. Launch a controlled browser to /
6. Wait for the preview-side signal
7. Print JSON results
8. Kill the full spawned process group during cleanup

3. Repeated runs

For --repeat N, print:

• per-run results
• summary stats grouped by server, browser, and total
• human-readable durations like 5.2s or 2m15s, not raw millisecond field names

Recommended summary fields:

{
  "server": {
    "average": "5.2s",
    "min": "4.8s",
    "max": "6.1s",
    "p95": "6.0s"
  },
  "browser": {
    "average": "1.9s",
    "min": "1.6s",
    "max": "2.4s",
    "p95": "2.3s"
  },
  "total": {
    "average": "7.1s",
    "min": "6.6s",
    "max": "8.2s",
    "p95": "8.1s"
  }
}

Interpretation Guidance

Use these heuristics when explaining results:

• If server grows, the regression is likely on the server/build side.
• If browser grows, the regression is likely in manager boot, preview boot, or first-story render.
• If averages are close but p95 grows a lot, the feature likely increases variability or tail latency.
• If newer Storybook without a feature is much faster than older Storybook, but enabling the feature returns timings to older levels, the feature likely erases the newer startup gains.

Common Pitfalls

• Existing Storybook already running on the benchmark port
• Storybook auto-opening a separate browser window
• Measuring direct iframe.html loads instead of normal /
• Leaving child Storybook processes alive between runs
• Treating warm repeated runs as cold-start data

If a repeated benchmark reports unrealistically low server.average, first check for a stale Storybook server on the same port.

Tooling Notes

• Prefer a plain Node script for portability.
• For Chrome-family browsers, remote debugging is a practical control path.
• If Storybook CLI flags or behavior are in question, fetch current Storybook docs first.

Output Style

When reporting results:

• clearly separate server, browser, and total
• call out averages and p95 first, with min/max as supporting bounds
• highlight whether the regression affects common-case latency, tail latency, or both
• avoid claiming root cause unless the benchmark isolates server vs render behavior

Example Triggers

Use this skill when the user says things like:

• "How can I test Storybook startup time?"
• "Measure from storybook dev to first story render"
• "Compare Storybook startup with and without this feature flag"
• "Run 20 startup measurements and summarize averages"
• "Is this startup regression server-side or render-side?"