CLI builder flag specification
You can provide a flag to Storybook's CLI to specify the builder you want to use with the command: `npx storybook@latest init --builder <webpack5 | vite>`
builders
54 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.
Default builder is Webpack 5
Storybook uses the Webpack 5 builder by default if you don't specify one.
Supported builders
Storybook supports three main builders: Vite builder for bundling stories with Vite with near-instant HMR; Webpack for bundling stories with Webpack with improved performance; and Rspack / Rsbuild for bundling stories with blazing fast Rspack and Rsbuild.
Storybook builders overview
Storybook is powered by builders such as Webpack and Vite. These builders spin up a development environment, compile your code—Javascript, CSS, and MDX—into an executable bundle and update the browser in real-time.
CLI auto-detection of builders
When you initialize Storybook via `npx storybook@latest init`, the CLI automatically detects which builder to use based on your application. For example, if you're working with Vite, it will install the Vite builder. If you're working with Webpack, it installs the Webpack 5 builder by default.
Supported builders in Storybook
Storybook is architected to support multiple builders including Webpack, Vite, and ESBuild.
Builder responsibility and function
In Storybook, a builder is responsible for compiling components and stories into JS bundles that run in the browser. A builder also provides a development server for interactive development and a production mode for optimized bundles.
How to enable a builder in Storybook
To opt into a builder, the user must add it as a dependency and then edit their configuration file (.storybook/main.js) to enable it.
Builder API start method for development
In development mode, the start API call is responsible for initializing the development server to monitor the file system for changes in components and stories, then execute a hot module reload in the browser. It also provides a bail function to allow the running process to end gracefully, either via user input or error.
Builder API build method for production
In production, the build API call is responsible for generating a static Storybook build, storing it by default in the storybook-static directory if no additional configuration is provided. The generated output should contain everything needed to view Storybook by opening either index.html or iframe.html in a browser with no other processes running.
Builder preview iframe responsibility
A builder is responsible for serving and building the preview iframe, which has its own set of requirements to fully support Storybook including essential features.
Stories configuration field for builders
The stories configuration field enables story loading in Storybook by defining an array of file globs containing the physical location of component stories. The builder must be able to load those files and monitor them for changes and update the UI accordingly.
Builder configuration in main.js
By default, Storybook's configuration is handled in a dedicated file (storybook/main.js|ts), giving users the option to customize it. The builder should also provide its own configuration support through additional fields or some other builder-appropriate mechanism.
Builder must handle preview.js exports
The preview.js configuration file allows users to control how stories render in the UI via the decorators named export. When Storybook starts, it converts these named exports into internal API calls via virtual module entry, such as addDecorator(). The builder must provide a similar implementation.
Builder MDX support requirement
Storybook's Docs includes the ability to author stories and documentation in MDX. The builder must know how to interpret MDX and invoke Storybook's special extensions.
Builder source code snippet generation
Storybook annotates components and stories with metadata related to their inputs to automatically generate interactive controls and documentation. The builder must re-implement this capability to support those features, as this is currently provided via Webpack loaders and plugins.
Builder static build generation
One of Storybook's core features is the ability to generate a static build that can be published to a web hosting service. The builder must provide a similar mechanism.
Builder development server integration
By default, when Storybook starts in development mode, it relies on its internal development server. The builder needs to be able to integrate with it.
Builder must provide server shutdown capability
The builder must provide a way to stop the development server once the process terminates, either via user input or error.
HMR support requirement for builders
While running in development mode, the builder's development server must be able to reload the page once a change happens in a story, component, or helper function.
Reference implementations for custom builders
When implementing a custom builder, reference implementations are available from Vite (https://github.com/storybookjs/storybook/tree/next/code/builders/builder-vite), Webpack (https://github.com/storybookjs/storybook/tree/next/code/builders/builder-webpack5), and Modern Web's dev-server-storybook (https://github.com/modernweb-dev/web/blob/master/packages/dev-server-storybook/src/serve/storybookPlugin.ts).
RFC required for proposing new builders
When ready to create a builder, open an RFC to discuss your proposal with the Storybook community and maintainers.
Vite handles more cases out of the box than Webpack
When migrating from Webpack to Vite, Vite generally handles more use cases out of the box. For example, loading styles just works for most projects, so you may not need all of your previous Webpack-specific configuration.
Start with minimal Vite configuration when migrating from Webpack
When migrating a Webpack-based project to Vite, it is recommended to start with no Storybook-specific Vite configuration and only add what your project actually requires.
Vite builder sets server.fs.strict for security
By default, the Vite builder enables Vite's `server.fs.strict` option for increased security, defining the project's `root` to Storybook's configuration directory. You can override this using the `viteFinal` function if needed.
Vite builder is the default Storybook builder
The Storybook Vite builder is the default builder and is recommended in most cases. It bundles components and stories with Vite, a fast ESM bundler.
Vite builder advantages for Vite applications
When using Storybook with applications built with Vite, the Vite builder allows reusing the existing Vite configuration in Storybook.
Vite builder trade-offs for Webpack applications
For applications built with Webpack, the Vite builder provides faster startup and refresh times. The disadvantage is that the component's execution environment differs from the application's environment.
Vite builder auto-installed with Storybook init
If you ran `npx storybook@latest init` to include Storybook in a Vite application, the Vite builder is already installed and configured automatically.
Configure Vite builder in main.js
To install and configure the Vite builder manually, run the install command and then update the `.storybook/main.js|ts` configuration file to include the builder.
viteFinal function for custom Vite configuration
Use the `viteFinal` configuration function in `.storybook/main.js|ts` to provide custom Vite configuration for Storybook. This asynchronous function receives a `config` object with the default builder configuration and returns the updated configuration.
Apply Vite configuration in vite.config.js for optimal experience
For an optimal experience when using the Vite builder, apply any configuration directly inside the Vite configuration file (vite.config.js|ts). Storybook automatically merges this configuration into its own when it loads.
Customize Vite config location with viteConfigPath
By default, the Vite builder searches for the Vite configuration file in the root directory. You can customize the location using the `viteConfigPath` option in `.storybook/main.js|ts`. If you do not want Storybook to load the Vite configuration file automatically, point `viteConfigPath` to a non-existent file.
Automatic argType inference support in Vite builder
Automatic argType inference is currently available for React, Vue 3, and Svelte (JSDocs only). With React, the Vite builder defaults to `react-docgen` for faster parsing. If needed, you can revert to `react-docgen-typescript` in the Storybook configuration file.
Interaction tests window object undefined error in Vite
When migrating from Webpack-based projects to Vite and using interaction testing, you may encounter an error that the `window` object is not defined. To resolve this, create a `preview-head.html` file in the Storybook configuration directory with appropriate Jest mock configuration.
Pass configLoader argument to Vite builder
You can pass the `configLoader` argument to the `vite` builder by setting it in builder options. This is equivalent to the `--configLoader` command line argument. Check Vite's documentation for valid `configLoader` options.
Configure Vite builder with TypeScript
To configure Storybook's Vite builder using TypeScript, rename `.storybook/main.js` to `.storybook/main.ts` and write the configuration in TypeScript syntax.
Webpack builder: compiler-agnostic approach
Storybook takes a compiler-agnostic approach to bundling, allowing you to bring your own application bundler such as Babel or SWC and ensuring compatibility within the Webpack 5-based project ecosystem.
Webpack builder with Babel: @storybook/addon-webpack5-compiler-babel addon
For projects that rely on Babel to provide support for specific features including TypeScript or other modern JavaScript features, use the `@storybook/addon-webpack5-compiler-babel` addon. When enabled, it adjusts the Webpack configuration to use babel-loader as the default loader for JavaScript and TypeScript files and detects and uses your project's Babel configuration.
Webpack builder: TypeScript module resolution troubleshooting
If TypeScript modules aliased from your tsconfig file are not being resolved within Storybook, use the tsconfig-paths-webpack-plugin while extending Storybook's Webpack config. Alternatively, if working with a framework that provides default aliasing (like Next.js or Nuxt), you can extend Storybook's default configuration to use the same aliases provided by the framework, such as configuring an alias for the @ import path in `.storybook/main.js|ts`.
Webpack builder: pre-bundled assets and managerWebpack limitation
Storybook relies on esbuild to build its internal manager, so support for bundling assets with managerWebpack will no longer have an impact on the Storybook UI. It is recommended to remove existing managerWebpack configuration elements from your Storybook configuration file and bundle assets other than images or CSS into JavaScript beforehand.
Webpack builder: Babel 8 bugfixes option removal
When using Babel 8 with Storybook, you may receive an error that the 'bugfixes' option has been removed. Storybook attempts to automatically detect and remove this option, but if detection fails, you can set the `babelRemoveBugfixes` feature flag in your Storybook configuration file to forcefully disable the bugfixes option.
Webpack builder: Webpack 4 no longer supported
Support for Webpack 4 has been removed and is no longer maintained. When upgrading Storybook, it will automatically use Webpack 5 and attempt to migrate your configuration. If working with a custom Webpack configuration, you may need to update it to work with Webpack 5 following the migration instructions on the Webpack website.
Webpack builder: based on Webpack 5
Storybook's Webpack configuration is based on Webpack 5, allowing it to be extended to fit your project's needs.
Webpack builder: historical builder for Storybook
The Storybook Webpack builder is the historical builder for Storybook. It enables creation of a seamless development and testing experience for components and provides an efficient way to develop UI components in isolation while leveraging existing Webpack configuration with Storybook.
Webpack builder: zero-config baseline configuration
By default, Storybook provides zero-config support for Webpack and automatically sets up a baseline configuration designed to work with the most common use cases.
Webpack builder configuration options table
The Webpack builder supports the following configuration options in the `.storybook/main.js|ts` file within `core: { builder: { options: { } } }`: lazyCompilation (enables Webpack's experimental lazy compilation feature), fsCache (configures Webpack's filesystem caching feature).
Webpack builder: webpackFinal configuration element
To override Storybook's default Webpack configuration, use the `webpackFinal` configuration element in `.storybook/main.js|ts`. It should export a function that receives the baseline configuration as the first argument and Storybook's options object as the second argument. When providing `webpackFinal`, you are responsible for merging the configuration yourself. You should preserve both the `entry` and `output` properties.
Webpack builder: append to plugins array, not overwrite
When customizing Storybook Webpack configuration by adding custom plugins or loaders, append changes to the `config.plugins` array rather than overwriting it. This is because Storybook relies on the `HtmlWebpackPlugin` to generate the preview page.
Webpack builder with SWC: @storybook/addon-webpack5-compiler-swc addon
For projects built using SWC, use the `@storybook/addon-webpack5-compiler-swc` addon. This addon increases ecosystem compatibility with Webpack 5 projects while maintaining high performance. When enabled, it adjusts the Webpack configuration to use the swc-loader for JavaScript and TypeScript files and detects and uses your project's SWC configuration.
Webpack builder: exclude .ejs file extension from custom loaders
When working with Webpack loaders that don't explicitly include specific file extensions via the `test` property, you should `exclude` the `.ejs` file extension for that loader.
Webpack builder: import existing Webpack configuration
If you have an existing Webpack configuration file, you can import it and merge it into Storybook's default configuration in the `.storybook/main.js|ts` file.
Webpack builder: debug configuration for static build
To debug the Webpack configuration used by Storybook when generating a static build, use the Storybook CLI with the appropriate debug command for build mode.
No Preview error with production build using serve package
When using the serve package to verify a production build of Storybook, a 'No Preview' error occurs because serve rewrites /iframe.html to /iframe. Use http-server instead with the command: npx http-server storybook-static