OpenWikistorybookjs/storybook

Vite Builder

Purpose and Scope

Storybook's Vite builder is the default and generally recommended builder for bundling components and stories with Vite, a fast ESM-based toolchain. The reader problem it solves is straightforward: a Storybook project needs a development server and production bundling path for the preview iframe, and that path should align with modern application builds whenever possible. For Vite applications, the builder can reuse the project's existing Vite configuration. For Webpack applications, it can improve startup and refresh speed, but it also means Storybook's browser execution environment may differ from the application runtime. Sources: docs/builders/vite.mdx

A builder in Storybook is not the same as a framework renderer. The renderer understands a component model such as React, Vue, Angular, or Web Components, while the builder compiles the project assets and stories into browser-ready bundles. In normal user projects, selecting a framework package such as a Vite-based React framework usually selects the Vite builder through framework configuration. The older direct builder package documentation still explains the builder's role clearly: it supports both interactive development mode and static production builds for Storybook stories. Sources: docs/builders/vite.mdx, code/builders/builder-vite/README.md

Relevant Source Files

  • docs/builders/vite.mdx — The primary public documentation page for the Vite builder, including setup, configuration merging, builder options, TypeScript setup, and Webpack migration troubleshooting.
  • code/builders/builder-vite/README.md — Package-level builder documentation that describes development and production usage, migration notes, custom Vite configuration, TypeScript, React Docgen, and working-directory considerations.

Installation and Framework Selection

If a project was initialized with Storybook inside an existing Vite application, the builder is already installed and configured by the initialization flow. The manual setup path is for projects that want to opt into Vite explicitly, or for projects migrating from another build system. The docs direct users to install the builder package as a development dependency and then update the Storybook configuration file so the project uses the Vite builder. The package README also notes that when a project has a root Vite configuration, Storybook can choose the Vite builder automatically during installation; otherwise, users historically supplied a builder flag. Sources: docs/builders/vite.mdx, code/builders/builder-vite/README.md

In current Storybook configuration, the most important decision is usually the framework package rather than a raw builder name. For example, a React project using Vite normally chooses the Vite-flavored React framework, and that framework arranges the builder integration. This distinction matters during migration because replacing Webpack dependencies alone is not enough; the Storybook configuration must also point at an appropriate Vite-based framework. The builder package README's migration checklist calls out choosing a Vite-based framework in the configuration, then starting Storybook with the same package scripts teams already use. Sources: code/builders/builder-vite/README.md

npm install @storybook/builder-vite --save-dev

Configuration Merging Model

Out of the box, Storybook's Vite builder starts from Storybook defaults for the supported frameworks and merges those defaults with the project's Vite configuration. The docs recommend putting general Vite settings in the application's Vite config file because that keeps application and Storybook behavior aligned. This is especially valuable for aliases, plugins, CSS handling, asset behavior, and other build-time assumptions that components depend on. Storybook loads that configuration automatically, merges it into its own builder configuration, and then allows final Storybook-specific customization when the shared configuration is not sufficient. Sources: docs/builders/vite.mdx

The escape hatch for Storybook-only changes is the asynchronous viteFinal configuration function in the Storybook main configuration file. This function receives the default builder configuration and returns the updated configuration that Storybook should use. The package README emphasizes returning the customized configuration and suggests using Vite's merge utility when recursively composing options. Use this hook for changes that are genuinely specific to Storybook, such as an alias used only in stories, a plugin needed for documentation examples, or an option that would be inappropriate for the production application build. Sources: docs/builders/vite.mdx, code/builders/builder-vite/README.md

// .storybook/main.ts
import type { StorybookConfig } from '@storybook/your-framework-vite';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework-vite',
  async viteFinal(config, context) {
    return config;
  },
};
 
export default config;

Builder Options and Environment-Specific Overrides

The Vite builder page documents two option-level customization paths in addition to viteFinal. First, the builder normally searches for the Vite configuration file in the root of the Storybook project, but viteConfigPath can point Storybook at a different file. That is useful in monorepos, packages with multiple build targets, or projects that intentionally keep Storybook's Vite configuration separate. The docs also call out an intentional edge case: pointing viteConfigPath at a non-existent file prevents Storybook from automatically loading the application's Vite configuration. Sources: docs/builders/vite.mdx

Second, the builder can pass a configLoader value through to Vite by setting the builder option. The documentation describes this as equivalent to Vite's command-line configLoader argument and defers the set of valid values to Vite's own configuration documentation. For environment-specific behavior, the docs recommend extending viteFinal with logic that inspects the Storybook configuration context. That keeps development, production, and other environment branches near the Storybook integration point while still preserving the default merged builder configuration as the starting point. Sources: docs/builders/vite.mdx

TypeScript and React Docgen Considerations

Storybook's Vite builder can be configured from TypeScript by renaming the main configuration file from a JavaScript extension to a TypeScript extension and adjusting the exported configuration accordingly. This matters for teams that want their Storybook configuration to be checked along with the rest of the project. Typed configuration is especially useful when framework options, builder options, and viteFinal hooks are all present, because it makes the available fields clearer and helps catch mistakes before a development server starts. The docs present this as an optional but supported configuration style. Sources: docs/builders/vite.mdx

React Docgen is part of the Vite builder's broader usage surface in the builder package documentation, even though the supplied public page excerpt does not include its detailed option text. Practically, React Docgen is the mechanism that extracts component metadata used by documentation tables and controls in React projects. When a Vite-based React Storybook has unexpected prop documentation, treat it as a framework-and-docgen configuration question rather than a generic bundling failure. Start by confirming the Vite framework package, then inspect any Storybook TypeScript and docs settings that affect component metadata extraction. Sources: code/builders/builder-vite/README.md

Migration from Webpack

The docs intentionally frame migration from Webpack as a simplification exercise rather than a one-to-one configuration translation. Vite handles many common front-end cases without explicit loader configuration, and style loading often works without carrying over previous Webpack rules. The recommended workflow is to remove Storybook-specific Vite customizations at first, run the project with the default Vite builder behavior, and add configuration only for requirements that are proven by the project. This avoids importing obsolete Webpack assumptions into a Vite setup. Sources: docs/builders/vite.mdx

The builder package README gives a concrete migration checklist: install Vite and the Vite builder, remove explicit Webpack-oriented dependencies such as webpack, react-scripts, Storybook Webpack builders, and old manager-webpack packages, select a Vite-based Storybook framework, clear Storybook Webpack cache, update application HTML for Vite expectations, and ensure files containing JSX use JSX-capable extensions. It also notes an older workaround for libraries expecting a browser global variable. Treat that list as historical package guidance, then verify each step against the current framework package and application stack. Sources: code/builders/builder-vite/README.md

Practical Next Steps

For a new project, prefer the standard Storybook initialization flow and let Storybook choose the Vite builder when it detects a Vite application. For an existing Storybook, first choose the matching Vite framework package, then keep general build settings in the project Vite configuration and reserve viteFinal for Storybook-only differences. If the project is in a monorepo or needs a separate configuration file, use viteConfigPath deliberately. If the project is migrating from Webpack, start from minimal configuration, verify stories render, and add Vite plugins or aliases only as required.

After this page, read the framework-specific page for the renderer you use, because React, Vue, Angular, Web Components, Svelte, and other integrations each add their own expectations on top of the builder. Then review the main configuration reference for the exact shape of the Storybook configuration file and the Webpack builder page if you need to compare builder tradeoffs. Teams that rely heavily on generated React documentation should also review the docs and TypeScript configuration pages alongside their Vite builder setup.

Ask a question...