Developer workflows
Storybook's developer workflows turn source changes into usable Storybook projects and evidence that those projects work. They cover project setup, version upgrades, code checks, cross-framework sandboxes, end-to-end tests, CI runs, and agent evaluations.
Workflow model
The repository uses one flow for local work and automation. A developer or CI job selects a task, the task runner prepares the needed project state, and the result is checked in the same kind of project that a Storybook user would run.
flowchart LR
A[Source change] --> B[Build and validate packages]
B --> C[Create or upgrade a project]
C --> D[Run sandbox checks and tests]
D --> E[Publish evidence or artifacts]
E --> F[CI status or evaluation result]
The important boundary is between monorepo code and a generated project. Package checks answer whether the repository can build. Sandbox checks answer whether the built packages can create, serve, build, and test real framework projects.
Workflow layers
The workflow layers serve different questions, so a failure in one layer does not replace the checks in the next layer:
- Package validation checks compilation, types, lint, and package shape.
- Project lifecycle checks create or upgrade a project and inspect the result.
- Sandbox checks exercise Storybook in supported frameworks and builders.
- Repository automation schedules work, distributes CI tasks, and reports results.
- Agent evaluation measures coding-agent behavior in controlled Storybook projects.
References: package.json• L19-43 scripts/task.ts• L79-104 code/package.json• L15-37
Project lifecycle
Project lifecycle tooling helps a developer move from an application without Storybook to a configured project, then keep that project current as Storybook changes. The lifecycle is exposed through the Storybook CLI and is tested against generated applications.
The setup package and the CLI are released on the same Storybook version line. This keeps project creation and later project maintenance aligned as developers move through a release.
Project setup
The setup flow detects the project and its package manager before it selects a framework generator. It checks feature support for the selected framework, builder, and renderer, then gathers valid feature choices. It writes the Storybook configuration, installs dependencies, configures addons, and gives the developer a command to start Storybook. An empty directory can first become a supported application through a small set of framework starters.
The setup command supports both interactive work and non-interactive agent work. Its options control feature selection, package installation, TypeScript support, the development server, logging, and telemetry so the same setup path can serve a person, CI, or an AI agent.
Project detection uses the project's dependency and peer-dependency signals. It keeps framework-specific version rules, such as the distinction between Remix 2 and Remix 3, so the selected generator matches the application that the developer has. It rejects unsupported, ambiguous, and Nx project types instead of creating a misleading setup.
The setup flow treats framework support as a product contract. Each generator must produce a project that matches the selected renderer, builder, and optional features. It checks whether testing and AI setup are available before it offers those features, then installs supported AI skills and records the user's choice for later Storybook behavior. Post-install generator work runs only after a successful dependency install. Addon synchronization also runs after installation when a preview configuration is available. For example, the Astro generator selects Vite as its builder and adds the builder package because the Astro framework package does not provide it.
Generators also select the story format supported by the framework. For frameworks with CSF factory support, setup writes the matching configuration and adjusts copied story imports so the generated project can resolve its preview configuration. See Project setup and migration for the project-facing lifecycle.
References: code/…/package.json• L1-41 code/…/run.ts• L22-86 code/…/run.ts• L112-135 code/…/types.ts• L74-137 code/…/initiate.ts• L46-69 code/…/initiate.ts• L78-245 code/…/ProjectTypeService.ts• L44-58 code/…/ProjectTypeService.ts• L181-225 code/…/baseGenerator.ts• L134-149 code/…/baseGenerator.ts• L275-338 code/…/csf-factories.ts• L10-51 code/…/csf-factories.ts• L76-105 code/…/index.ts• L6-19
Project upgrades
The upgrade flow keeps one or more Storybook projects aligned with the selected CLI version. It updates Storybook dependencies, applies safe automigrations, installs the resulting dependency tree, configures deferred addons after installation, refreshes existing Storybook skills, and runs a health check. Its summary separates successful projects, projects that need attention, and projects with no applicable changes.
When it searches for projects, the upgrade flow avoids .storybook directories inside ignored trees, dependency trees, and nested repositories while still checking the current working directory. This keeps repository-wide discovery focused without making a directly selected project invisible.
Separate from dependency upgrades, the CLI can run named codemods over matching story or configuration files. The command supports listing migrations, dry runs, glob selection, and optional file-suffix changes. A rename runs only after all matching files process without errors, so a partial source migration does not also rename files.
Automigrations remove settings that are no longer meaningful when a version boundary makes a feature permanently active. For Storybook 11, the legacy argTypeTargetsV7 and disallowImplicitActionsInRenderV8 flags are removed from the main configuration rather than left as stale settings. The upgrade checks also keep the TypeScript support needed for component type reading aligned with the renderer. They can add a missing TypeScript peer dependency, propose a usable TypeScript version when the native docgen API is not available, or report the side-by-side package change needed when no automatic upgrade exists.
References: code/…/package.json• L1-42 code/…/upgrade.ts• L354-491 code/…/upgrade.ts• L493-584 code/…/upgrade.ts• L628-643 code/…/migrate.ts• L25-71 code/…/migrate.test.ts• L49-64 code/…/migrate.test.ts• L150-189 code/…/util.test.ts• L28-125 code/…/csf-factories.ts• L77-175 code/…/remove-legacy-feature-flags.ts• L4-33 code/…/typescript-dependency.ts• L17-53 code/…/typescript-dependency.ts• L55-115
Upgrade blockers
Upgrade blockers are pre-flight checks that stop an upgrade when a project no longer meets Storybook's support policy. The checks run for each project in parallel, then group the same message with the affected configuration directories so the developer receives one actionable result.
The dependency checks use the effective version supplied by the package manager, including versions bundled by tools that provide Vite or Vitest. They enforce shared framework and builder floors, while optional floors apply only when the Storybook addon that needs them is present. Experimental React builds with a 0.0.0 version remain allowed because their version string does not describe their supported API.
The test-runner blocker protects the Storybook 11 upgrade boundary. It detects @storybook/test-runner when it is declared or installed and directs the developer either to the Vitest addon migration path or to remain on Storybook 10. The blocker registry is the contract that makes these checks part of the common upgrade path.
| Blocker group | Upgrade decision |
|---|---|
| Dependency support floors | Ask the developer to upgrade an incompatible framework, builder, or gated test package before upgrading Storybook. |
| Removed test runner | Ask the developer to migrate to the Vitest addon or keep the project on Storybook 10. |
References: code/…/index.ts• L9-43 code/…/block-dependencies-versions.ts• L6-65 code/…/block-test-runner.ts• L5-27 code/…/utils.ts• L26-61 code/…/utils.ts• L71-131 code/…/block-dependencies-versions.test.ts• L133-183 code/…/block-test-runner.test.ts• L28-70
CLI diagnostics
The info command gives a compact view of the local environment so a developer can diagnose setup and runtime problems. It runs a pinned envinfo package through the active package manager, reports Storybook-related packages and common tools, and marks the active package manager in the output. If the remote package cannot be downloaded, it reports a handled error instead of exposing an unstructured failure.
The main CLI routes setup, addon changes, upgrades, diagnostics, migrations, sandboxes, links, automigrations, and health checks through one command surface. It applies shared logging and failure handling around these actions, which gives local runs and automation a consistent exit status and debug-log path.
References: code/…/run.ts• L31-90 code/…/run.ts• L92-234 code/…/info.ts• L11-49 code/…/info.test.ts• L26-59 code/…/run.test.ts• L33-82
Validation and test projects
The repository validates both its own packages and the user projects that consume them. Generated sandboxes provide repeatable applications across frameworks, builders, languages, and release lines.
Package validation
Package validation builds the monorepo in dependency order and checks the source of each workspace. The task runner can link local packages for fast development or use production-style package outputs for a closer release check. Type checks run per workspace and can also run in watch mode for local feedback.
This layer is the first signal for a source change. It does not prove that a framework project can initialize or that a built Storybook can render stories.
The package build turns each buildable workspace into its published shape. A package declares its source entries and supported targets, and the build produces JavaScript, package export metadata, and declaration output for those entries. Developers can build selected packages or all buildable packages in development or production mode, while production builds also verify the public type surface.
The type output keeps package boundaries clear. Shared declarations can serve normal entries, while selected public entries can be emitted as portable files for consumers that must not depend on unrelated type chunks. This makes package validation cover both the code bundle and the way downstream Storybook projects resolve the package.
References: scripts/…/compile.ts• L17-50 scripts/…/check.ts• L43-94 scripts/check-package.ts• L20-71 scripts/build-package.ts• L31-55 scripts/build-package.ts• L110-125 scripts/…/build-package.ts• L57-125 scripts/…/entry-utils.ts• L7-64 scripts/…/generate-package-json.ts• L8-53 scripts/…/generate-types-rolldown.ts• L298-493 scripts/…/entry-utils.test.ts• L5-54
Sandbox lifecycle
Sandbox tooling creates a base application with its native framework tool, adds Storybook through the same setup path used by users, and preserves the result as a reproducible fixture. The task graph then runs only the stages needed for the requested outcome, such as type checking, building, serving, or browser tests.
Each template states the framework, renderer, and builder that it expects. It can also record known limits so the shared workflow does not treat an intentionally unsupported test as a product failure. See Testing fixtures and sandboxes for the fixture and suite view.
References: code/…/sandbox-templates.ts• L33-140 scripts/task.ts• L58-104 scripts/…/generate.ts• L237-407
Test suites
Sandbox tests cover different user risks instead of repeating one test at many levels. Smoke and build checks show that Storybook starts and produces output. Portable story projects exercise Jest, Vitest, optional Playwright end-to-end tests, and Cypress component tests. A separate MCP project checks the addon's end-to-end flow and its Storybook story tests. Type checks catch project-level errors that package checks cannot see.
The MCP endpoint suite checks the contract used by agent tools. It verifies session negotiation, tool discovery, focused and full story tests, accessibility results, invalid story errors, toolset filtering, and the HTML response for browser clients. It also checks that concurrent test requests complete in order through the endpoint's serialized test path.
The sandbox task runner records task results and diagnostics so CI can show which framework and task failed. The CI test-storybook jobs also keep the shared build prerequisite explicit, which prevents these projects from testing an incomplete package state. This makes a failure useful for both local reproduction and automated triage.
See Ecosystem quality assurance for the wider checks that protect Storybook integrations outside the generated project suites.
References: scripts/…/check-sandbox.ts• L5-14 scripts/…/vitest-test.ts• L19-65 scripts/task.ts• L242-271 scripts/…/test-storybooks.ts• L7-70 scripts/…/test-storybooks.ts• L72-130 test-storybooks/…/mcp-endpoint.e2e.test.ts• L32-1128
Repository automation
Repository automation turns the local workflow into repeatable checks on pull requests, branch updates, schedules, and manual runs. It selects the required work, prepares package state, publishes sandbox results, and exposes status back to the repository.
CI orchestration
CI focus logic uses changed paths to reduce work without losing broad checks. It maps a changed package to the highest-priority sandbox role that loads it, then adds the other Chromatic siblings that load the same package. Changes to shared inputs, such as lockfiles, workspace configuration, or shared test setup, trigger the full affected test path because file-level test tracing cannot safely capture their reach.
The same selection also adds path-specific setup, portable story, MCP, and internal Storybook jobs. Every focused run keeps build, affected checks, lint and format, Chromatic, and sandbox result reporting in the job set. This gives small changes a fast path while preserving wider coverage for changes with broad reach.
CircleCI selects one or more workflow classes and generates the matching job configuration. Documentation workflows can run only formatting, Windows workflows select Windows build, unit, and sandbox work, and daily workflows add cross-platform, docgen, and runtime smoke gates to the normal Linux checks. GitHub Actions runs the broader package and sandbox task set through Nx when that workflow is enabled, while a scheduled or manual job generates and publishes framework sandboxes. The same task names are used locally and in CI, which keeps local reproduction close to the automated path.
The sandbox publication flow uses a local package registry when it needs to test the current checkout. It publishes only completed generated projects and sanitizes them before sending them to the shared sandbox repository.
See Repository automation for trigger rules, job ownership, and release automation.
References: scripts/…/focus.ts• L27-35 scripts/…/focus.ts• L62-129 scripts/…/focus.ts• L131-209 scripts/…/global-inputs.ts• L1-10 scripts/…/global-inputs.test.ts• L5-53 scripts/…/main.ts• L17-123 scripts/…/workflow-jobs.ts• L27-77 .circleci/config.yml• L29-64 .github/…/nx.yml• L29-103 .github/…/generate-sandboxes.yml• L95-122 scripts/…/publish.ts• L35-91
Agent evaluation
The agent-evaluation platform runs controlled tasks against Storybook projects to measure whether coding agents can create, change, test, and inspect UI work. Standard evaluations run from pull requests or schedules and publish result artifacts plus a review or playground summary.
The agentic-reference flow adds a larger case matrix. It generates experiment entry points from a case registry, resolves an explicit selection, and can run the work in batches so partial results remain useful. Existing qualifying runs count toward a plan unless the operator requests a forced collection.
See Agent evaluation platform for the evaluation model, result handling, and paid-run controls.
References: agent-eval/package.json• L10-34 agent-eval/…/generate-agentic-ref-experiments.ts• L69-129 agent-eval/…/run-agentic-ref.ts• L41-114 agent-eval/…/run-plan.ts• L390-527 .github/…/agent-eval.yml• L174-229
Change checklist
When these files or sections are changed, remember to consider these:
- When adding a framework or builder, update its project generator, project detection rules, sandbox expectations, cadence membership, and any deliberate task skips together.
- When changing setup feature support or post-install work, keep feature selection, generator output, dependency installation, addon configuration, and the final developer command aligned.
- When changing setup command options or agent mode, keep interactive defaults, non-interactive behavior, telemetry, log-file handling, and command-level tests aligned.
- When changing framework support for CSF factories, keep the support matrix, generated main and preview configuration, and copied story preview imports aligned.
- When changing an upgrade fix or codemod, keep its version boundary, source edits, result summary, and health check outcome aligned. For TypeScript fixes, also keep renderer support, docgen API checks, and the user-facing migration path aligned.
- When changing a removed integration or dependency support floor, keep blocker registration, effective-version detection, user guidance, and migration links aligned. Conditional floors must remain gated by the addon that needs them.
- When changing explicit codemod rename behavior, keep dry-run handling, suffix matching, and the no-rename-on-error guard aligned.
- When changing package outputs or workspace dependencies, check both linked development sandboxes and production-style sandbox installs.
- When changing package entry maps, export metadata, or declaration settings, verify that JavaScript output, package resolution, and the public type surface still describe the same entries.
- When changing package external-dependency rules, verify both normal declarations and portable public entries. A dependency can be valid at runtime but still need a different boundary in the type output.
- When changing project discovery, preserve the rules for ignored trees, nested repositories, dependency directories, and direct working-directory lookup.
- When changing sandbox generation or publication, preserve the completed-fixture marker and the rules that remove local install state before publication.
- When changing CI path selection or global-input rules, check that focused sandboxes, sibling Chromatic jobs, path-triggered jobs, and full-suite escalation still match the change's reach.
- When changing workflow classes or job membership, check that focus, docs, Windows, daily, and normal workflows still select the intended gates and no-op jobs.
- When changing the MCP tool contract, keep tool discovery, toolset filtering, request serialization, error output, and the endpoint's client-facing response shape aligned.
- When changing agent-evaluation cases or selection flags, regenerate the work directory and keep the runner, plan tool, and CI inputs on the same selection contract.
- When changing CI labels, workflow inputs, or deployment targets, update the matching gate and result-reporting steps in the same workflow.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A project dependency matches the wrong framework rule or version range | Setup selects the wrong generator or stops before creating Storybook | Detection uses ordered framework rules and rejects unsupported or ambiguous project types |
| A sandbox's generated framework does not match its declared expectation | Generation or later checks fail, which signals a framework integration regression | Template expectations are checked during the sandbox lifecycle |
| A workspace is selected for a build but has no build configuration | An explicit build stops, while an all-package build skips that workspace | The build entry point rejects explicit non-buildable selections and filters them from all-package builds |
| A package entry changes without matching its export or declaration settings | Downstream projects can resolve a missing module or receive a type surface that does not match the runtime package | Package metadata and declaration output are generated from the same entry definitions |
| Parallel builds expose a partially written package manifest | Another package can fail while reading an invalid package configuration | Manifest updates replace the completed file rather than exposing a truncated write |
| A focused CI run misses a global input or fixture change | A change can pass a narrow job set even though it affects unrelated tests | Global-input and fixture rules escalate to the full relevant test path |
| The required Storybook packages are not compiled or are linked with an incompatible framework | The sandbox tests the wrong package state or fails during install and startup | The task graph makes install and compile prerequisites explicit |
| A local-registry generation run leaves the registry changed after an error | Later installs use the wrong package source | Registry use restores the public registry in a final cleanup path |
| An upgrade changes dependencies but an automigration or deferred addon step fails | The project may have mixed versions or incomplete configuration | Upgrade results classify failures and run a doctor check before completion |
| A setup or upgrade post-install step needs a package that was not installed successfully | The project can finish with incomplete generator or addon setup | Post-install work runs only after a successful install, and the user receives a warning when it fails |
| A TypeScript version cannot provide the docgen API for the active renderer | Controls and the Docs args table cannot read component types after upgrade | The automigration checks renderer support and either adds, upgrades, or clearly reports the required TypeScript package path |
| A bundled tool reports its host package version instead of its bundled Vite or Vitest version | A supported project can be blocked, or an unsupported project can pass the upgrade gate | Dependency checks use the effective bundled version when the package manager exposes it |
| A conditional dependency floor runs without its gating Storybook addon | Projects that do not use the addon receive an unrelated upgrade blocker | Conditional checks first confirm that the addon is installed |
@storybook/test-runner is declared or installed during a Storybook 11 upgrade | The upgrade continues with an integration that Storybook 11 no longer supports | The test-runner blocker checks both declaration and installation state and gives two supported paths forward |
| A framework is marked for CSF factory setup but its generated story imports do not match the preview configuration | New stories can fail to load after setup | The generator limits factory setup to supported frameworks and rewrites copied story preview imports to the generated config path |
| A codemod changes some files but another matching file cannot be parsed | Source files can be inconsistent if file renames also continue | The migration leaves files in place when errors occur and renames only after a clean run |
| The environment-info package cannot be downloaded from the npm registry | The info command cannot collect diagnostics | The command reports the registry error as a handled failure and includes the cause |
| The MCP endpoint exposes a changed tool count or response shape without matching the client contract | Agents cannot discover or call the expected Storybook tools | Endpoint tests cover initialization, discovery, filtered toolsets, focused results, errors, and response formats |
| Concurrent MCP test requests share the Storybook test runner without serialization | Requests can interfere with each other or return the wrong story results | The endpoint serializes test-run work and the end-to-end suite checks concurrent calls |
| An agent evaluation starts without the required API or deployment credentials | The job fails or can produce no useful evaluation result | CI validates credentials before running experiments and checks for result files |
| An evaluation selection does not match the active case registry | No unintended experiment runs, but the requested work stops before spending | Selection resolves against the active registry and rejects unmatched input |
Key files
| File | Why to read it |
|---|---|
| scripts/task.ts | Defines the shared task graph, prerequisites, readiness, and task result handling. |
| scripts/build-package.ts | Provides the developer-facing selection for package builds and separates buildable workspaces from other workspaces. |
| scripts/…/build-package.ts | Coordinates one package build and its bundle, package metadata, and type outputs. |
| scripts/…/entry-utils.ts | Defines the package entry contract and the dependency boundaries used by bundles and declarations. |
| scripts/…/generate-package-json.ts | Shows how build entries become package export metadata for downstream consumers. |
| scripts/…/generate-types-rolldown.ts | Shows the production path that turns package source into shared or portable declaration output. |
| code/…/package.json | Defines the published installer package and its release relationship to project setup. |
| code/…/run.ts | Defines setup options for interactive, automated, and agent-driven project creation. |
| code/…/initiate.ts | Shows the user-facing setup flow from project detection to a ready Storybook command. |
| code/…/types.ts | Defines the contract between project selection, framework configuration, and post-install work. |
| code/…/baseGenerator.ts | Shows how setup turns framework support and selected features into dependencies, configuration, scripts, and starter stories. |
| code/…/csf-factories.ts | Defines which frameworks use CSF factory setup and keeps copied story preview imports valid. |
| code/…/ProjectTypeService.ts | Shows how the setup flow maps application signals to a supported project type. |
| code/…/index.ts | Illustrates how a framework generator declares its renderer, builder, and setup additions. |
| code/…/package.json | Defines the published CLI package and its release relationship to project upgrades. |
| code/…/run.ts | Defines the CLI command surface and shared logging, telemetry, and failure behavior. |
| code/…/upgrade.ts | Shows how dependency upgrades, automigrations, addon setup, skill refresh, and health checks form one lifecycle. |
| code/…/index.ts | Registers the pre-upgrade blockers and runs their checks as one project-level result. |
| code/…/block-dependencies-versions.ts | Defines shared and addon-gated dependency support floors for upgrade decisions. |
| code/…/block-test-runner.ts | Defines the Storybook 11 boundary for the removed test runner and its migration guidance. |
| code/…/utils.ts | Turns package versions and blocker results into grouped developer-facing upgrade messages. |
| code/…/block-dependencies-versions.test.ts | Captures the support-floor, bundled-version, and addon-gated dependency contract. |
| code/…/block-test-runner.test.ts | Captures detection of declared or installed test-runner projects and the two migration paths. |
| code/…/migrate.ts | Defines explicit codemod selection, dry-run behavior, and guarded file renames. |
| code/…/info.ts | Shows how the CLI collects and marks local environment information for diagnosis. |
| code/…/csf-factories.ts | Shows how a source migration chooses import style and updates stories and configuration. |
| code/…/remove-legacy-feature-flags.ts | Illustrates a version-bound configuration cleanup during upgrade. |
| code/…/typescript-dependency.ts | Shows how upgrades keep TypeScript and the renderer's docgen API compatible. |
| scripts/…/main.ts | Shows how selected workflows become merge-gating or nightly CircleCI jobs. |
| scripts/…/focus.ts | Shows how changed paths select focused sandboxes and related CI jobs. |
| scripts/…/global-inputs.ts | Defines the changes that require broad test coverage. |
| scripts/…/workflow-jobs.ts | Maps workflow classes to their normal, daily, Windows, documentation, and focused job sets. |
| scripts/…/test-storybooks.ts | Shows how portable story and MCP projects become CI test jobs with explicit build prerequisites. |
| code/…/sandbox-templates.ts | Defines the supported project matrix and the expected integration contract for each template. |
| scripts/…/generate.ts | Shows how real framework applications become reproducible before-and-after Storybook sandboxes. |
| scripts/…/check.ts | Shows the monorepo-wide type validation boundary. |
| scripts/…/vitest-test.ts | Shows how sandbox test output and browser diagnostics become CI evidence. |
| test-storybooks/…/mcp-endpoint.e2e.test.ts | Defines the end-to-end contract for MCP session setup, tool discovery, story tests, filtering, and client responses. |
| .github/…/generate-sandboxes.yml | Shows the scheduled and manual path from compiled packages to published sandboxes. |
| agent-eval/…/run-agentic-ref.ts | Shows selection and spend controls for the agentic-reference evaluation matrix. |
| agent-eval/…/run-plan.ts | Shows how evaluation deficits become resumable batches and reports. |