Introducing a new way to review your PRs.

Read the announcement

storybookjs / storybook

Storybook is the industry standard workshop for building, documenting, and testing UI components in isolation

View on GitHub

20 documents · Updated Nov 20, 2026

docs / cli-and-server-lifecycle

CLI and server lifecycle

Storybook turns a project command into a live development site, a static site, or a story index. The CLI selects the mode and gathers project options. core-server then loads configuration, composes presets, selects the manager and preview builders, and coordinates the result. This page describes that path within the broader Storybook runtime, with links to the Manager UI, Preview runtime and story rendering, and Story format and analysis.

Command entry and modes

Command dispatch

The CLI entry point checks the Node.js version and routes core commands to the Storybook core binary. The core commands are dev, build, and index. Other commands use separate CLI packages, so they can change project state without directly selecting a core-server builder.

The core binary maps each command to one of three results:

CommandResult
devA running Storybook development server with manager and preview applications
buildA self-contained static Storybook site
indexA JSON story index without a web server

References: code/…/dispatcher.ts• L15-25 code/…/dispatcher.ts• L53-57 code/…/core.ts• L26-37

Run context

Each command combines CLI options with a project context before it enters core-server. The context identifies the configuration directory, run type, cache, package metadata, and command-specific paths. Development uses development mode. Static builds use production mode and write to storybook-static unless the user selects another output path.

The CLI also controls logging and telemetry around the process. A command reports failures at its boundary. A successful static build exits after all output work completes.

References: code/…/dev.ts• L37-62 code/…/build.ts• L4-17 code/…/core.ts• L67-93 code/…/core.ts• L148-189

Project initialization

storybook init prepares the project for later dev and build runs. It detects the project type and the matching renderer and builder. It then creates configuration, installs dependencies, and configures addons. Optional onboarding state is recorded only after setup succeeds.

Initialization may request a development run. In that case it starts the project command as a separate process after dependency setup. This keeps project preparation separate from the long-lived server process.

References: code/…/initiate.ts• L78-180 code/…/initiate.ts• L185-262 code/…/initiate.ts• L278-359

Project maintenance commands

The separate cli-storybook command surface handles setup and maintenance around the core lifecycle. Commands such as add, migrate, automigrate, link, and upgrade change packages or project configuration. Later core runs read those changes during preset and builder resolution.

This boundary matters because maintenance commands do not start the core server themselves. Their output becomes input to a later dev, build, or index run.

References: code/…/run.ts• L47-90 code/…/add.ts• L87-197 code/…/codemod.ts• L34-120 code/…/link.ts• L20-29 code/…/upgrade.ts• L354-397

Configuration and preset resolution

Project configuration

core-server reads the selected project configuration before it builds or starts anything. That configuration defines the framework, renderer, builder, story locations, features, addons, and other extensions that shape the Storybook instance.

A preset is a configuration extension that contributes values to named Storybook settings. Presets run in order. Framework and addon presets can therefore add to or adjust shared settings before the builders consume them. A caller can also supply a channel or override presets when Storybook runs inside another host.

The common override preset adds a small policy layer for special build modes. Test builds can remove MDX entries, skip docgen, and turn off related build features while normal builds keep the shared defaults.

References: code/…/presets.ts• L347-356 code/…/presets.ts• L359-385 code/…/load.ts• L28-60 code/…/common-override-preset.ts• L5-55

Builder selection

Storybook resolves builders in two passes. The first pass identifies the framework, renderer, and preview builder. The second pass composes the common, renderer, builder, addon, and project presets into the final runtime context.

The preview builder owns the framework-specific preview application. The manager builder owns the Storybook interface. The two builders remain separate while the development server coordinates them through a shared channel.

The selection relationship is summarized below.

flowchart LR
  Config[Project configuration] --> First[First preset pass]
  First --> Choice[Framework, renderer, builder]
  Choice --> BuilderPreset[Builder preset]
  BuilderPreset --> Final[Final preset pass]
  Final --> Manager[Manager builder]
  Final --> Preview[Preview builder]

References: code/…/load.ts• L62-125 code/…/build-dev.ts• L153-231 code/…/build-static.ts• L63-117 code/…/get-builders.ts• L12-35

Shared services

The common preset connects the selected runtime to shared services. These services provide the story index, module graph, change detection, review data, documentation data, and tool access used by the server and attached tools.

The preset creates one story index generator promise for the active process. It builds that generator from normalized story locations, indexers, documentation settings, features, and story sorting rules. The same index view then supports development updates, static output, and service queries.

References: code/…/common-preset.ts• L373-433 code/…/common-preset.ts• L490-512 code/…/common-preset.ts• L514-565

Development server lifecycle

Server startup

The dev command resolves the port, public addresses, cache output, and server channel before it starts Storybook. It loads the final presets and gives the shared options to core-server. The server then starts the manager and preview applications under one HTTP server.

The startup flow moves from command input to a usable Storybook URL:

  1. Resolve the host, port, and public addresses.
  2. Load configuration and select the builders.
  3. Create the shared channel for the manager, preview, and server services.
  4. Start the manager unless preview-only mode is active.
  5. Start the preview and story index services.
  6. Listen for requests and optionally open a browser.

Browser opening can be skipped or delegated to a script. A missing launcher is reported as a warning so it does not stop the server.

References: code/…/dev.ts• L37-62 code/…/build-dev.ts• L49-73 code/…/build-dev.ts• L102-151 code/…/build-dev.ts• L153-296 code/…/opener.ts• L32-76 code/…/opener.ts• L94-127

Development services

The development server exposes the story index, static files, project metadata, and configured middleware beside the manager and preview. It also starts change detection so source changes can update the index and preview during the same process.

The story index watches the directories covered by the configured story locations. It filters events to matching story and docs files, batches rapid events, and invalidates affected entries. A change to preview configuration can invalidate the full index because project tags can affect every entry. The manager and preview receive updates through the shared server channel. See Manager UI and Preview runtime and story rendering for those consumers.

References: code/…/dev-server.ts• L32-59 code/…/dev-server.ts• L65-107 code/…/dev-server.ts• L158-200 code/…/index-json.ts• L17-76 code/…/watch-story-specifiers.ts• L7-53

Change detection

Change detection marks stories affected by source changes so review and related tools can show current project state. It combines the Git working-tree view with the module graph and story index. It maps changed files to direct and dependent stories, then publishes modified, affected, and new statuses.

The status pipeline waits until the module graph is ready. It scans once at startup and debounces later scans from file activity or Git state changes. Git state watching is opportunistic. If Git is unavailable or the watcher fails, the service reports an unavailable or error state without taking down the server.

The flow from project change to story status is:

flowchart LR
  Files[Working tree or Git state] --> Diff[Changed file sets]
  Diff --> Graph[Module graph]
  Graph --> Stories[Affected story IDs]
  Stories --> Status[Status store]
  Status --> Clients[Review and Storybook tools]

GitDiffProvider treats staged, unstaged, intent-to-add, and untracked files as current changes. With a since reference it adds files committed on the branch after the branch fork point. Deleted files are excluded. Git reads use disabled optional locks so scans do not race an interactive commit.

References: code/…/GitDiffProvider.ts• L47-115 code/…/GitDiffProvider.ts• L117-147 code/…/GitDiffProvider.ts• L149-278 code/…/change-detection-service.ts• L196-271 code/…/change-detection-service.ts• L284-415 code/…/GitDiffProvider.since.test.ts• L47-138

Story index state

The story index generator turns configured story and docs files into entries used by the manager and preview. It caches matching files and extracted results. It also restarts a build when a file changes during indexing so the result matches one source revision.

The index includes story and docs tags, autodocs entries when enabled, links between MDX pages and stories, and the configured story order. It is versioned and can produce a compact summary for telemetry and build reports. See Story format and analysis for parsing and analysis details.

References: code/…/StoryIndexGenerator.ts• L111-145 code/…/StoryIndexGenerator.ts• L247-294 code/…/StoryIndexGenerator.ts• L426-465 code/…/StoryIndexGenerator.ts• L467-585 code/…/StoryIndexGenerator.ts• L683-735 code/…/StoryIndexGenerator.ts• L742-808

Development shutdown

The server treats a failed preview start as a process failure and stops active builders. On normal termination it disposes change detection and other active subscriptions before the process exits. This keeps an interrupted or failed builder from leaving a live server behind.

References: code/…/dev-server.ts• L142-155 code/…/dev-server.ts• L189-229 code/…/change-detection-service.ts• L254-271

Static build lifecycle

Static site assembly

The build command runs core-server in production mode and cleans the output directory before assembly. It asks the manager and preview builders to produce files instead of starting listeners. The same broad configuration and preset model applies as in development.

The deployable output can include:

  • The manager application unless preview-only mode is active.
  • The preview application from the selected builder.
  • User static files and browser assets.
  • index.json with the available stories.
  • Optional metadata, open-service files, and component manifests.

The build reports success only after all required output work completes. Telemetry failure does not make an otherwise complete site fail. When a manifest uses MDX service data, the service files are written before the manifest references them.

MDX documentation uses one contract for the live service and static output. In development, manifests resolve references from the service. In a static build, they resolve the same references from service snapshot files, while shallow indexes can keep summary data beside each reference.

References: code/…/build-static.ts• L41-61 code/…/build-static.ts• L63-123 code/…/build-static.ts• L140-249 code/…/mdx-manifest.ts• L12-18 code/…/mdx-manifest.ts• L80-103 code/…/mdx-ref-resolution.ts• L58-76 code/…/manifests.ts• L247-328

Story index generation

The index command uses the same configuration and preset model but stops at story discovery. It writes the generated index to the requested file without starting the manager, preview, or web server.

This gives other processes Storybook's view of the project's stories without the cost of a full site build. The index generator discovers files, extracts entries, processes docs, applies tags and sorting, and checks for invalid duplicates.

References: code/…/buildIndex.ts• L11-28 code/…/build-index.ts• L12-45 code/…/StoryIndexGenerator.ts• L84-105 code/…/StoryIndexGenerator.ts• L753-899

Lifecycle boundaries

Core-server boundary

The CLI owns command parsing, user-facing options, and process-level reporting. core-server owns the shared lifecycle after those options are resolved. Its public entry point exposes development, static build, and index generation paths. It also exposes shared server services for callers that embed or extend Storybook.

The boundary creates a contract between command defaults and runtime inputs. CLI options must form valid core-server options. Core-server changes must preserve the contracts expected by the manager and preview builders.

References: code/…/index.ts• L3-15 code/…/index.ts• L98-128 code/…/standalone.ts• L5-34 code/…/common-preset.ts• L373-391

Change checklist

When these files or sections are changed, remember to consider these:

  • Changes to CLI defaults must remain valid for the matching core-server entry point and run mode.
  • Changes to the first preset pass must still allow builder and renderer contributions in the second pass.
  • Changes to common build overrides must keep test-only feature switches separate from normal development and production behavior.
  • Changes to common services must preserve one shared story index and one active services registration for the process.
  • Changes to builder selection must preserve both manager and preview startup and build contracts.
  • Changes to file or Git change detection must preserve path mapping from repository paths to story IDs.
  • Changes to Git baseline handling must preserve staged, unstaged, untracked, intent-to-add, and branch-since behavior.
  • Changes to change detection readiness must keep scans behind a ready module graph and must not publish results from a transient graph state.
  • Changes to static output assembly must preserve the order between service files, manifests, and index.json.
  • Changes to the MDX service contract must keep live-service payloads and static snapshot references compatible.

Important failure modes

TriggerConsequenceGuard
Unsupported Node.js versionThe CLI stops before command dispatch.The dispatcher checks the supported version first.
No builder in the composed configurationThe preview cannot start or build.Builder selection reports a missing-builder error.
Preview startup or build failsThe command fails and active builders stop.Core-server performs failure cleanup.
Git is unavailable or the project is not a Git repositoryGit-based change detection becomes unavailable.The service reports an unavailable state and stops its Git pipeline without stopping Storybook.
Git ref is unknown or shares no commit with HEADA since change query fails.The provider validates the ref and merge base and gives a fetch-history message for unrelated shallow history.
Git watcher failsLater Git state changes may not update statuses until restart.The provider closes failed watchers and logs a warning; module graph scans remain separate.
A scan starts while the module graph patch is incompleteStory statuses can reflect a transient reverse index.The service waits for the graph status and drains the loaded graph before scanning.
Empty or root output directory is selectedStatic build cleanup is refused.Static build validates the resolved output path before removal.
MDX service data is referenced before its output existsStatic manifest references can point to missing data.The build writes service snapshots before manifest references.
MDX service and static manifest paths divergeDevelopment and static documentation views resolve different data or fail to load.Keep the shared payload shape, service path, and JSON pointer contract aligned.
Services preset is applied twiceThe server can register duplicate services.Common preset rejects a second services application.

Key files

FileWhy to read it
code/…/dispatcher.tsSee how CLI arguments reach core or external command packages.
code/…/core.tsSee the core commands and command-level defaults.
code/…/dev.tsSee how the development command enters core-server.
code/…/build.tsSee how the static build command enters core-server.
code/…/index.tsSee the public core-server lifecycle and service boundary.
code/…/load.tsSee configuration loading and two-pass preset resolution.
code/…/common-override-preset.tsSee build-mode overrides that shape test and normal runs.
code/…/build-dev.tsSee development setup and builder startup.
code/…/dev-server.tsSee server, indexing, listening, and shutdown coordination.
code/…/build-static.tsSee static site assembly and output ordering.
code/…/build-index.tsSee the configuration-only story index flow.
code/…/common-preset.tsSee shared services, the story index generator, and change detection wiring.
code/…/GitDiffProvider.tsSee Git change queries and opportunistic Git state watching.
code/…/change-detection-service.tsSee how file changes become story statuses.
code/…/GitDiffProvider.since.test.tsSee the contract for branch diffs, untracked files, refs, and shallow history.
code/…/StoryIndexGenerator.tsSee how story and docs files become a cached index.
code/…/get-builders.tsSee the manager and preview builder boundary.
code/…/mdx-manifest.tsSee the shared MDX service and static manifest contract.
code/…/mdx-ref-resolution.tsSee how live and disk MDX references resolve into manifests.
code/…/manifests.tsSee how MDX snapshots feed static component manifests.
code/…/initiate.tsSee project detection, setup, dependency installation, and optional startup.