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 / webpack-presets

Webpack presets

Webpack presets are reusable Storybook configuration layers for React and server-rendered HTML. They connect a framework package to the Webpack 5 builder, then add the rules and metadata support needed to turn that framework’s stories into a working Storybook preview. See Framework and build integration for the wider model, Builder integrations for builder behavior, and Framework packages and Renderer packages for the surrounding package roles.

Package roles

The framework packages are the user-facing integration points. The preset packages hold shared Webpack behavior so the framework package can select the builder, renderer, and framework-specific configuration without owning all of the build rules.

React Webpack preset

The React Webpack preset adds React-oriented Webpack behavior to a Storybook build. It supports React component stories and can add component metadata for docs and controls through the legacy builder-side docgen path. Its public config types describe the React-specific docgen options used by that path.

The package exposes the main preset plus dedicated docgen entry points. It is intended for React 18 or 19 projects and treats the docgen providers as optional peers, so a project can choose the metadata path that matches its build.

References: code/…/package.json• L23-31 code/…/package.json• L55-73 code/…/framework-preset-react-docs.ts• L15-49 code/…/types.ts• L10-46

The React Webpack 5 framework package composes this preset with the Webpack 5 builder and the React renderer. It also keeps React resolution aligned with the application and marks development builds so the preview behaves like a development environment.

References: code/…/preset.ts• L9-36 code/…/package.json• L28-63

Server Webpack preset

The server Webpack preset lets Storybook treat JSON and YAML story descriptions as preview modules. It converts those descriptions into Storybook story definitions during the build, so the server renderer can request HTML for the selected story instead of rendering a client-side component.

The package exposes the preset and its loader as public entry points. Its only Storybook peer is the main storybook package, while YAML support is part of the preset package contract.

References: code/…/package.json• L23-30 code/…/package.json• L39-51 code/…/index.ts• L7-33 code/…/loader.ts• L1-12 code/…/index.ts• L8-17

The Server Webpack 5 framework package composes this preset with the Webpack 5 builder and the server renderer. The resulting integration is for UI whose final HTML comes from an application server rather than from React code in the preview bundle.

References: code/…/preset.ts• L3-10 code/…/README.md• L34-63

Preset layering

Preset layering is the contract that lets a framework add focused behavior to a shared builder. A framework selects the builder and renderer first, then its preset contributes the framework rules before user configuration receives the final Webpack configuration.

Framework selection

The framework preset defines the pairing between a framework and its build system. React selects @storybook/builder-webpack5, @storybook/react, and the React Webpack preset. Server selects the same builder with @storybook/server and the server Webpack preset. This keeps framework identity separate from the builder’s common compilation work.

References: code/…/preset.ts• L9-16 code/…/preset.ts• L3-10

Configuration flow

The Webpack 5 builder gathers the webpack preset result, applies shared defaults, and then runs the webpackFinal chain. A project-level Webpack file can take full control after those layers, so framework behavior is a base for the build rather than a replacement for project configuration.

References: code/…/index.ts• L71-84 code/…/custom-webpack-preset.ts• L79-101

The flow below shows how a framework choice becomes a preview build.

flowchart LR
    A[Framework package] --> B[Builder and renderer selection]
    B --> C[Framework Webpack preset]
    C --> D[Shared Webpack defaults]
    D --> E[Final preset hooks]
    E --> F[Optional project Webpack config]
    F --> G[Webpack preview compilation]

Framework build behavior

The two presets solve different input problems while sharing the same build lifecycle. React starts from JavaScript and TypeScript component modules. Server starts from data files that describe stories and turns them into modules that the renderer can use.

React story builds

React builds combine the React renderer with Webpack rules that can extract component information for Storybook docs. Server-side docgen owns metadata extraction when features.docgenServer is enabled, so the preset leaves the preview configuration unchanged in that mode. Otherwise, the preset prepares the configured legacy builder docgen mode before it adds a loader or TypeScript plugin. These builder-side options are deprecated in favor of server-side docgen.

References: code/…/framework-preset-react-docs.ts• L15-49 code/…/types.ts• L26-42

The preset preserves the project’s existing Webpack rules and plugins when it adds React docgen support. The loader follows project TypeScript path mappings when it resolves component definitions and leaves source available for normal compilation when parsing fails. In TypeScript mode, the plugin receives the configured options and keeps default prop values in the same string form as the other docgen path.

References: code/…/framework-preset-react-docs.ts• L50-107 code/…/react-docgen-loader.ts• L71-183

Server story builds

Server builds use the story file format as the source of the preview module. JSON files are compiled directly, while YAML files first become JSON and then pass through the same Storybook conversion step. The result gives the server renderer a normal story model while the actual HTML remains owned by the configured server endpoint.

References: code/…/index.ts• L7-33 code/…/README.md• L93-101

The server framework therefore depends on a boundary outside Webpack: Storybook selects a story and sends its server identifier and parameters to the application server. Webpack prepares the story definitions, but it does not render the final HTML.

References: code/…/README.md• L20-30 code/…/README.md• L63-87

Build lifecycle

After preset composition, the Webpack 5 builder creates the preview compiler. Development mode keeps the compiler connected to middleware and hot updates, while a production build runs the compiler to completion and writes the preview output.

References: code/…/index.ts• L139-247 code/…/index.ts• L271-339

The builder reports Webpack warnings and fails the Storybook build when compilation errors remain. This makes preset compatibility part of the shared builder contract: a framework preset must return a usable Webpack configuration for both development and production paths.

References: code/…/index.ts• L222-240 code/…/index.ts• L290-321

Change checklist

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

  • When changing a framework’s core selection, check that its addons list still loads the matching preset and that its renderer matches the story input model.
  • When changing a preset’s Webpack rules, check both the default builder path and the project custom-config path because the latter receives the already-layered result.
  • When changing server story formats or compiler output, check the loader rule, the generated story module shape, and the server renderer contract together.
  • When changing React docgen behavior, check the relationship between features.docgenServer, typescript.reactDocgen, optional builder docgen packages, and TypeScript docgen options so metadata is not extracted twice or lost.
  • When changing builder preset order, check that framework hooks run before the final user override and that both development and production compilation still receive the same base configuration.

Important failure modes

TriggerConsequenceGuard
A framework selects a builder or renderer that does not match its presetStories can load with the wrong compilation rules or renderer contractKeep each framework’s core, addons, and story input model aligned
A server story file does not match the JSON or YAML rulesThe file is not converted into a Storybook story moduleKeep supported story extensions covered by the server preset rules
The main config enables server-side docgen while builder docgen remains configuredPreview metadata can be extracted by the wrong path or more than oncePrefer server-side docgen and remove the deprecated builder-side setting
Builder docgen packages or a selected mode cannot be preparedThe preset does not add builder-side metadata extractionPrefer server-side docgen or provide the optional package support required by the legacy mode
React source cannot be parsed by the docgen loaderThe preview can still compile, but component metadata is missingRun Storybook with debug logging and fix the source or its import paths
A custom Webpack config replaces the layered result instead of extending itFramework rules or builder defaults disappear from the preview buildTreat the received final configuration as the base for custom changes
A preset adds rules without preserving existing rules or pluginsAddon and project behavior can silently stop workingMerge framework additions with the incoming configuration

Key files

FileWhy to read it
code/…/preset.tsShows how the React framework selects the builder, renderer, and React preset.
code/…/preset.tsShows the corresponding server framework composition.
code/…/package.jsonShows the React preset’s public entry points and framework-facing peer contract.
code/…/index.tsDefines the React preset entry and its docs configuration layer.
code/…/framework-preset-react-docs.tsExplains the React metadata behavior added to Webpack.
code/…/react-docgen-loader.tsShows how legacy React docgen metadata is added and how parse failures are handled.
code/…/types.tsDefines the React docgen configuration contract and its deprecated builder-side options.
code/…/framework-preset-react-docs.test.tsShows the supported React docgen modes and fallback behavior.
code/…/package.jsonShows the server preset’s public entry points and package contract for YAML-backed story inputs.
code/…/index.tsDefines the server story-file rules added to Webpack.
code/…/loader.tsShows how server story data becomes a build-time Storybook module.
code/…/custom-webpack-preset.tsShows how defaults, preset hooks, and project Webpack configuration are layered.
code/…/index.tsShows how the composed configuration becomes a development or production preview build.