Vite and Webpack builders
The Vite and Webpack 5 builders give Storybook one contract for serving and building the preview. Each builder turns Storybook options into a bundler config, runs the preview in development or production mode, and returns the status data that core-server uses to report results and handle errors. See Framework and build integration for the wider system view. Related pages: Framework packages, Renderer packages, and Webpack presets.
Builder contract
The builder contract separates Storybook orchestration from bundler work. Core-server selects the preview builder from the core preset, loads its optional presets, then calls the same lifecycle methods for either bundler.
| Contract part | Purpose |
|---|---|
getConfig | Exposes the resolved bundler config for inspection and tooling. |
start | Starts the development preview and attaches it to the Storybook server. |
build | Creates the static preview output. |
bail | Stops an active development server or build. |
corePresets and overridePresets | Adds builder rules to the wider preset chain. |
changeDetectionAdapter | Gives core-server module resolution and file-change access. |
The result of start includes a stop function, elapsed time, and optional stats. The result of build is optional stats. This lets core-server report common outcomes without knowing the bundler API.
References: code/…/core-common.ts• L189-203 code/…/core-common.ts• L313-345
Vite builder
The Vite builder uses Vite as a middleware server in development and as the static bundler in production. It combines the project Vite config with Storybook's preview entry and runtime plugins so stories, addons, environment data, and framework code share one module graph. The @storybook/builder-vite package supports Vite 6, 7, and 8 through its peer dependency contract.
Vite configuration
The Vite config starts with the project root and a Storybook plugin set. It can load a user Vite config by discovery or by the viteConfigPath builder option. An explicit null value opts out of loading a user config. The viteFinal hook receives the merged config and can change it before the server or build starts.
References: code/…/vite-config.ts• L92-117 code/…/vite-config.ts• L137-190 code/…/types.ts• L12-35 code/…/package.json• L30-38 code/…/package.json• L60-63
The builder keeps the two config modes aligned while applying mode-specific behavior:
| Mode | Builder behavior |
|---|---|
| Development | Uses Vite's serve mode, middleware mode, strict file access, and HMR through the Storybook HTTP server. It serves iframe.html through middleware rather than as a Vite entry. |
| Production | Uses Vite's build mode and writes bundles to Storybook's output directory without removing files that core-server has already placed there. It adds iframe.html as the build entry and can apply the chunked preview runtime. |
The development server serves the transformed iframe.html route and passes the remaining requests to Vite. The production build returns Webpack-shaped stats when the stats plugin can provide them, which preserves a common reporting shape for core-server and external tools. When stats are requested, the plugin also maps Vite's module graph to the dependency shape used by Storybook's change and snapshot tools. It keeps project paths relative to the working directory, preserves virtual modules, and can connect watched resources to the module that registered them.
References: code/…/vite-server.ts• L9-45 code/…/code-generator-plugin.ts• L45-68 code/…/webpack-stats-plugin.ts• L47-76 code/…/webpack-stats-plugin.ts• L118-185 code/…/index.ts• L21-34 code/…/build.ts• L18-44 code/…/build.ts• L98-107
Vite runtime behavior
Vite plugins create the Storybook entry graph and connect it to the preview runtime. They generate virtual story and addon modules, inject the mocking runtime into the preview page, and update the story graph or mock state when watched source files change. Production builds expose the mocker runtime through a separate entry, while development uses a base-aware URL so Vite can resolve it through the dev server.
The transformed iframe.html carries the resolved Storybook settings into the browser. It includes framework, feature, story, docs, tags, channel, security, and custom head or body data. In development it also rewrites the virtual app module URL to the Vite dev-server form, so the same HTML template works with Vite's virtual module graph.
References: code/…/code-generator-plugin.ts• L25-43 code/…/plugin.ts• L20-71 code/…/transform-iframe-html.ts• L8-61 code/…/preset.ts• L17-43 code/…/vite-config.ts• L154-188
Vite change detection
The Vite builder exposes the module resolution and file-change signals that Storybook uses to track the preview graph. The server-bound adapter takes a one-time snapshot of the project root, aliases, and import conditions from Vite. It forwards only file additions, changes, and removals with normalized paths, and it provides an unsubscribe function for cleanup.
The headless adapter gives tools that do not run a Vite server the same resolution view. It assembles the development config, applies viteFinal, and asks Vite to resolve the result in serve mode. It returns the root, aliases, and conditions used for ESM imports. Because no watcher exists in this mode, file-change callbacks are no-ops and each invocation builds a fresh view.
Vite's combined development|production condition is converted to the active mode, and the import condition is added because Vite applies it during ESM resolution without listing it in the config. This keeps change detection aligned with the package export path that the preview uses.
References: code/…/index.ts• L13-66 code/…/headless.ts• L7-38 code/…/import-conditions.ts• L1-16 code/…/index.test.ts• L41-152 code/…/headless.test.ts• L28-80
Webpack 5 builder
The Webpack 5 builder uses the preset system to assemble a Webpack configuration and then runs a Webpack compiler. Its development path connects Webpack Dev Middleware and hot middleware to the Storybook server. Its production path runs the compiler to completion and copies the preview runtime into the output.
Webpack configuration
The Webpack config begins with Storybook and framework preset values. The builder adds the default asset and module rules unless core disables them, then applies webpackFinal and an optional project Webpack config. The final config is available through getConfig, so core-server and debugging tools can inspect the same config used by the compiler.
The published @storybook/builder-webpack5 package also exposes the preview presets, loaders, and templates that support this integration. These exports form part of the package contract used by Storybook and related tooling.
References: code/…/index.ts• L71-85 code/…/custom-webpack-preset.ts• L79-104 code/…/types.ts• L19-33 code/…/package.json• L29-44
The preview config changes the compiler for the requested mode:
| Mode | Builder behavior |
|---|---|
| Development | Uses development output names, hot replacement, Webpack Dev Middleware, and hot middleware. |
| Production | Uses hashed output names, optimization, and a completed compiler run for static files. |
The config also supplies the preview HTML, story entries, virtual modules, environment values, and optional TypeScript checks. Builder options can add a file cache or lazy compilation for development.
References: code/…/iframe-webpack.config.ts• L35-49 code/…/iframe-webpack.config.ts• L110-124 code/…/iframe-webpack.config.ts• L141-192 code/…/types.ts• L52-55
Webpack runtime behavior
The development builder waits for a valid compiler result before it reports success. It forwards warnings and compilation errors through the builder result or an error, and its bail path closes middleware and the compiler so a failed sibling build does not keep the process active.
The Webpack preview also applies sb.mock declarations from the preview config during module resolution. It matches declarations to Webpack's resolved resources, supports manual __mocks__ replacements and spy-based automocks, and can redirect a bare package before browser resolution rejects it. A declaration that Webpack cannot resolve is warned about and skipped, so other mocks can still apply.
References: code/…/index.ts• L201-246 code/…/index.ts• L89-117 code/…/webpack-mock-plugin.ts• L18-119 code/…/webpack-mock-plugin.test.ts• L173-249
The builder exposes a change-detection adapter only after it creates the Webpack compiler. The adapter lets core-server use Webpack's resolution rules and compiler events rather than maintain a separate view of the preview graph.
References: code/…/index.ts• L119-131 code/…/core-common.ts• L334-344
Core-server consumption
Core-server treats the selected preview builder as a lifecycle service. It discovers the builder from the core preset, loads builder presets before the full preset pass, then uses the builder in either the development server or static build flow.
flowchart LR
A[Core preset] --> B[Select preview builder]
B --> C[Load builder presets]
C --> D{Core-server mode}
D -->|Development| E[builder.start]
D -->|Static build| F[builder.build]
E --> G[Preview middleware and HMR]
F --> H[Preview assets in output directory]
E --> I[Result: time and stats]
F --> I
I --> J[Core-server reporting and failure handling]
The development flow starts the manager and preview builders on the shared server. After the preview starts, core-server asks for the change-detection adapter and starts its change service. A Vite builder supplies a Vite-backed adapter, while a Webpack builder supplies a compiler-backed adapter.
References: code/…/dev-server.ts• L97-168 code/…/build-dev.ts• L260-291
The static flow prepares the output directory, loads the selected builder, and runs the preview build beside core-server's index, static files, metadata, and service assets. Core-server consumes returned stats for optional stats output and wraps builder errors with the common build error path.
References: code/…/build-static.ts• L40-111 code/…/build-static.ts• L139-212 code/…/get-builders.ts• L16-35
Change checklist
When these files or sections are changed, remember to consider these:
- Changes to
Builderresult fields must stay compatible with both Vite's no-dev-stats behavior and Webpack's stats reporting. - Changes to builder presets must be checked against core-server's two-pass preset load. A builder may add presets needed before
startorbuildruns. - Changes to output directory ownership must preserve the shared static build. The builder must not remove files that core-server writes before or beside the preview assets.
- Changes to
changeDetectionAdaptermust keep module resolution rules aligned with the bundler that serves the preview. - Changes to mode flags must update both the builder config and the middleware or static-build path that consumes its result.
- Changes to the Vite iframe.html entry or virtual module URLs must preserve the difference between development middleware serving and production bundling.
- Changes to Vite mocker injection must keep the development URL under Vite's base and the production URL relative to the hosted artifact path.
- Changes to the Vite stats adapter must preserve relative file names, virtual module names, import edges, and watched-resource ownership expected by snapshot and change tools.
- Changes to Vite change detection must keep server-bound and headless resolution views aligned. Preserve the active mode condition, the ESM
importcondition, normalized file events, and the headless no-op watcher contract. - Changes to Webpack mock resolution must preserve manual bare-package redirects, matching for both module conditions, and the loader context used by replacement modules.
- Changes to the Vite package peer range or export map must preserve the published entry points and the supported Vite versions.
- Changes to the Webpack package export map must preserve the preset, loader, and template paths used by the builder integration.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| No builder is selected by the core preset | Core-server cannot start or build the preview. | MissingBuilderError is raised before the builder lifecycle begins. |
| Vite development stats are requested as if they were Webpack stats | Smoke-test or stats output code receives no usable preview stats. | Core-server accepts NoStatsForViteDevError for Vite development mode. |
| Webpack config suppresses stats | The builder cannot check warnings or errors from the compiler. | The builder rejects none and summary stats modes. |
| A bare package has a manual mock but browser resolution rejects the package first | The preview can fail before Webpack replaces the package with its mock. | Webpack applies the manual redirect during the early resolution step. |
| A declared mock cannot be resolved with the active Webpack rules | That mock is ignored while the rest of the preview continues. | The builder logs a warning and keeps the resolved mock map usable. |
| A Vite preview config changes without mocker invalidation | The browser can keep stale mock behavior until another update occurs. | The Vite mocker plugin sends a custom invalidate-mocker event when the preview config changes. |
| A Vite config changes while the server-bound change adapter is active | Change detection can use stale aliases or import conditions. | The adapter snapshots resolver settings at startup, so the Storybook process must restart after resolver config changes. |
| A headless Vite consumer expects live file events | Its graph does not update during the invocation. | The headless adapter has no live server or watcher; the consumer must build a new view when it needs fresh data. |
| The production Vite mocker script uses a root-relative path on a subpath host | The built preview cannot load its mocking runtime from a non-root deployment path. | Production injection uses a relative ./vite-inject-mocker-entry.js URL. |
| Preview compilation has errors | Core-server marks the preview operation as failed and stops the related process. | Both builders surface compilation failures through their lifecycle promise. |
| Builder stop runs while middleware or compilation is active | The process can keep serving or print late compiler output. | Builder bail closes the active server or compiler before it resolves. |
| The Vite package is installed with an unsupported Vite version | Package resolution can fail or the builder can run outside its supported contract. | The package declares Vite 6, 7, or 8 as peer versions. |
Key files
| File | Why to read it |
|---|---|
| code/…/core-common.ts | Defines the shared builder contract and result shape. |
| code/…/build-dev.ts | Shows builder selection, preset loading, and development orchestration. |
| code/…/dev-server.ts | Shows how core-server starts the manager and preview and binds change detection. |
| code/…/build-static.ts | Shows how preview output joins the rest of the static Storybook output. |
| code/…/vite-config.ts | Explains Vite config merging and mode-independent setup. |
| code/…/package.json | Defines the Vite package entry points and supported peer versions. |
| code/…/code-generator-plugin.ts | Shows how Vite creates virtual preview modules and selects the development or production iframe path. |
| code/…/webpack-stats-plugin.ts | Shows how Vite exposes a common module graph for stats and change tools. |
| code/…/webpack-stats-plugin.test.ts | Shows the supported module naming, import graph, and watched-resource behavior. |
| code/…/plugin.ts | Shows how the Vite preview loads and refreshes its mocking runtime. |
| code/…/transform-iframe-html.ts | Shows how resolved Storybook settings become preview HTML. |
| code/…/index.ts | Defines the Vite builder lifecycle exposed to core-server. |
| code/…/index.ts | Defines the live Vite resolver snapshot and file-event contract. |
| code/…/headless.ts | Defines resolver access for Vite consumers without a dev server. |
| code/…/import-conditions.ts | Defines the import conditions shared by live and headless resolution. |
| code/…/index.ts | Defines Webpack 5 lifecycle, compiler status, and shutdown behavior. |
| code/…/package.json | Defines the Webpack builder package exports and its bundling dependencies. |
| code/…/iframe-webpack.config.ts | Shows the Webpack preview config for development and production. |
| code/…/custom-webpack-preset.ts | Shows how default and user Webpack config are combined. |
| code/…/webpack-mock-plugin.ts | Explains how Webpack applies preview mock declarations during bundling. |
| code/…/webpack-mock-plugin.test.ts | Shows the supported mock outcomes across aliases, package conditions, loaders, and unresolved declarations. |