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: 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() Check whether the repo already has a benchmark script. Reuse it if possible. 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 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: Fail fast if the target Storybook port is already in use Spawn Storybook with --no-open Start timing immediately before spawn Wait for HTTP readiness on the Storybook URL Launch a controlled browser to / Wait for the preview-side signal Print JSON results 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?"