React and Next.js

Purpose and Scope

This page helps React and Next.js teams choose the right Storybook framework path and understand how the builder choice affects local development. Storybook’s React-family frameworks all serve the same product goal: develop, test, and document UI components in isolation, while still fitting the application’s bundler and framework conventions. For modern React and most Next.js projects, the practical default is the Vite-based experience because Storybook’s Vite builder is documented as the default builder and recommended in most cases. That default matters because it shapes startup speed, refresh behavior, configuration merging, and test support.

Sources: docs/builders/vite.mdx

The React and Next.js framework choices are easiest to understand as a layered decision. First choose the renderer or application framework: React, React with Vite, React with Webpack 5, Next.js with Vite, or Next.js with Webpack. Then choose whether Storybook can reuse an existing Vite configuration or must stay close to a Webpack environment. Official framework guidance recommends Storybook for Next.js with Vite for most Next.js applications, while keeping the Webpack framework available for projects with custom Webpack configuration, custom Babel requirements, or Webpack-specific features that are not available through Vite.

Relevant Source Files

• docs/builders/vite.mdx — Defines the Storybook Vite builder, its setup path, configuration model, builder options, TypeScript support, and migration guidance from Webpack.

Core Primitives

A framework package is the Storybook integration you select for your app type, such as React Vite or Next.js Vite. A builder is the lower-level system that bundles the preview iframe containing your rendered stories. In the Vite path, the builder bundles components and stories with Vite, a fast ESM bundler, and Storybook merges its builder defaults with the project’s existing Vite configuration. The most important project files are the Storybook main configuration file and the Vite configuration file, because together they determine story discovery, addon registration, framework options, and final bundler behavior.

Sources: docs/builders/vite.mdx

The official Next.js Vite documentation frames that integration as the recommended framework for developing and testing isolated UI components in Next.js applications. It names Next.js version 14.1 or newer and Vite version 5 or newer as requirements in the supplied docs evidence. The official Next.js Webpack documentation describes the Webpack framework as using Webpack 5 and explicitly recommends the Vite-based framework for most projects. In practice, that means new Next.js projects should start with Next.js Vite unless an existing build pipeline depends on Webpack-only features or custom Babel behavior.

Setup Flow

For an existing React or Next.js project, start by running the standard Storybook creation command from the project root. The installer detects the project, adds Storybook configuration, and selects an appropriate framework. If the project already uses Vite, the Vite builder path is expected to be ready after initialization. The Vite builder docs state that when Storybook is initialized in a Vite application, the builder is already installed and configured, while manual opt-in remains available for projects that need to change builders after the initial setup.

Sources: docs/builders/vite.mdx

npm create storybook@latest

After installation, inspect the Storybook main configuration rather than immediately adding custom builder code. For Vite projects, Storybook automatically merges the project’s Vite configuration with Storybook’s own defaults. The docs recommend placing normal application bundler configuration in the Vite configuration file, then using Storybook’s main configuration only for Storybook-specific adjustments. This keeps React aliases, plugins, and resolve behavior close to the application build while preserving a clear override point when a story preview needs behavior that the application itself does not require.

Sources: docs/builders/vite.mdx

System-to-Code Mapping

Configuration and API Components

The key extension point for React and Next.js Vite projects is the asynchronous Vite finalization function in Storybook’s main configuration. The docs describe this function as receiving the default builder configuration and returning the updated configuration. Use it for Storybook-only aliases, plugins, environment-specific changes, or compatibility fixes that should not be part of the application’s normal Vite file. For broader Vite behavior, prefer the application Vite configuration file so that the app and Storybook continue to share as much bundler behavior as possible.

Sources: docs/builders/vite.mdx

The builder also exposes options for locating and loading Vite configuration. By default, Storybook searches for the Vite configuration file in the root directory of the Storybook project. If the file lives somewhere else, configure the builder with a custom Vite configuration path. If automatic loading is not desired, the documented technique is to point that option at a non-existent file. The docs also mention a config loader option that maps to Vite’s command-line config loader behavior, which is useful when a repository standardizes how Vite config files are evaluated.

Sources: docs/builders/vite.mdx

Choosing Vite or Webpack

Use React Vite or Next.js Vite when the goal is the fastest common development loop and the component code can run correctly in Vite’s browser-oriented ESM environment. This is especially natural for applications already built with Vite because Storybook can reuse the project configuration. For applications built with Webpack, the Vite builder can still offer faster startup and refresh times, but the docs call out an important tradeoff: the component execution environment differs from the application. That difference should be evaluated before migrating highly customized Webpack projects.

Sources: docs/builders/vite.mdx

Choose a Webpack 5 framework when the project depends on Webpack behavior that is not easily represented in Vite. The official Next.js Webpack guidance names custom Webpack configurations, custom Babel configurations, and specific Webpack features as reasons to stay on the Webpack-based Next.js framework. When migrating from a Webpack or Create React App-style setup, the Vite builder docs recommend starting with no Storybook-specific Vite configuration and adding only what the project proves it needs. That prevents old loader rules from becoming unnecessary compatibility baggage.

Sources: docs/builders/vite.mdx

Next Steps

After selecting a React or Next.js framework, create or review stories for the components that represent important states, then run Storybook and verify that styling, imports, environment assumptions, and framework-specific modules behave correctly in the preview. If the app uses Next.js features, validate the recommended Next.js Vite path first, then fall back to Webpack only for concrete incompatibilities. If a Vite configuration adjustment is needed, place general app behavior in the Vite config and reserve the Storybook main configuration for Storybook-only builder changes.

Sources: docs/builders/vite.mdx