Webpack

Storybook Webpack 构建器是 Storybook 的默认构建器。此构建器使您能够为组件创建无缝的开发和测试体验，并提供一种高效的方式来隔离开发 UI 组件，从而使您能够将现有的 Webpack 配置与 Storybook 结合使用。

配置

默认情况下，Storybook 为 Webpack 提供零配置支持，并自动设置基线配置，以适用于最常见的用例。但是，您可以扩展 Storybook 配置文件（即 .storybook/main.js|ts），并提供其他选项来提高 Storybook 的性能或根据您的需求进行自定义。下面列出了可用的选项以及如何使用它们的示例。

选项	描述
`lazyCompilation`	启用 Webpack 的实验性`lazy compilation` `core: { builder: { options: { lazyCompilation: true } } }`
`fsCache`	配置 Webpack 的文件系统缓存功能 `core: { builder: { options: { fsCache: true } } }`

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-webpack5',
      options: {
        fsCache: true,
        lazyCompilation: true,
      },
    },
  },
};
 
export default config;

覆盖默认配置

Storybook 的 Webpack 配置基于 Webpack 5，允许对其进行扩展以适应您项目的需求。如果您需要添加加载器或插件，您可以在 .storybook/main.js|ts 文件中提供 webpackFinal 配置元素。配置元素应导出一个函数，该函数接收基线配置作为第一个参数，并将 Storybook 的选项对象作为第二个参数。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
};
 
export default config;

当 Storybook 启动时，它会自动将配置合并到自身中。但是，当提供 webpackFinal 配置元素时，您需要自行负责合并配置。我们建议您负责任地处理对 config 对象的更改，同时保留 entry 和 output 属性。

使用 Webpack 插件

自定义 Storybook 配置的另一种方法是添加自定义插件或加载器，以帮助进行代码优化、资产管理或其他任务。然而，由于 Storybook 依赖于 HtmlWebpackPlugin 来生成预览页面，我们建议您将更改附加到 config.plugins 数组，而不是覆盖它。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    config.plugins.push(/* ... */);
    return config;
  },
};
 
export default config;

此外，当使用不显式包含特定文件扩展名（即通过 test 属性）的 Webpack 加载器时，您应该为该加载器 exclude .ejs 文件扩展名。

导入自定义 Webpack 配置

如果您已经有一个现有的 Webpack 配置文件，需要与 Storybook 重用，则可以导入它并将其合并到默认配置中。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import custom from '../webpack.config.js'; // 👈 Custom Webpack configuration being imported.
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    return {
      ...config,
      module: { ...config.module, rules: [...config.module.rules, ...custom.module.rules] },
    };
  },
};
 
export default config;

基于生成器搭建的项目可能需要您导入其特定的 Webpack 配置文件。我们建议您阅读生成器的文档以获取更多信息。

调试 Webpack 配置

如果您打算调试 Storybook 使用的 Webpack 配置，可以使用 Storybook CLI 来帮助您。如果您在开发模式下运行，则可以使用以下命令

npm run storybook -- --debug-webpack

此外，如果您正在生成 Storybook 的静态构建，则可以使用以下命令

npm run build-storybook -- --debug-webpack

编译器支持

Storybook 采用与编译器无关的方式进行捆绑。这使您可以自带应用程序捆绑器（例如，Babel、SWC），并确保与基于 Webpack 5 的庞大项目生态系统内的兼容性。

SWC

如果您的项目是使用 SWC 构建的，请使用 @storybook/addon-webpack5-compiler-swc 插件。此插件提高了与 Webpack 5 项目的生态系统兼容性，同时保持了高性能。运行以下命令以自动设置插件

npx storybook@latest add @storybook/addon-webpack5-compiler-swc

可以提供其他选项来自定义 SWC 配置。有关更多信息，请参阅SWC API 文档。

启用后，此插件会调整 Webpack 配置以使用 swc-loader 处理 JavaScript 和 TypeScript 文件。此外，它将检测并使用您项目的 SWC 配置。

Babel

如果您正在处理一个依赖 Babel 工具来提供对特定功能（包括 TypeScript 或其他现代 JavaScript 功能）支持的项目，则可以使用 @storybook/addon-webpack5-compiler-babel 插件，以便在您的 Storybook 中包含它们，从而确保与您的项目兼容。运行以下命令以自动设置插件

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

可以提供其他选项来自定义 Babel 配置。有关更多信息，请参阅 babel API 文档，或者如果您正在开发插件，请参阅 babelDefault 文档以获取更多信息。

启用后，该插件将调整 Webpack 配置，以使用 babel-loader 作为 JavaScript 和 TypeScript 文件的默认加载器。此外，它将检测并使用您项目的 Babel 配置。

Storybook 的默认 Webpack 配置为大多数项目设置提供支持，而无需任何额外的配置。然而，根据您的项目配置或选择的框架，当从您的 tsconfig 文件中别名化 TypeScript 模块时，您可能会遇到 TypeScript 模块在 Storybook 中未解析的问题。如果您遇到此问题，您可以使用 tsconfig-paths-webpack-plugin，同时按照以下方式扩展 Storybook 的 Webpack 配置

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.plugins = [
        ...(config.resolve.plugins || []),
        new TsconfigPathsPlugin({
          extensions: config.resolve.extensions,
        }),
      ];
    }
    return config;
  },
};
 
export default config;

但是，如果您正在使用提供默认别名配置的框架（例如，Next.js、Nuxt），并且您希望配置 Storybook 以使用相同的别名，则可能无需安装任何其他软件包。相反，您可以扩展 Storybook 的默认配置，以使用框架提供的相同别名。例如，要为 @ 导入路径设置别名，您可以将以下内容添加到您的 .storybook/main.js|ts 文件中

.storybook/main.ts

import path from 'path';
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@': path.resolve(__dirname, '../src'),
      };
    }
    return config;
  },
};
 
export default config;

预捆绑的资源未在 Storybook UI 中显示

由于 Storybook 依赖 esbuild 来构建其内部管理器，因此使用 managerWebpack 捆绑资源将不再对 Storybook UI 产生影响。我们建议从您的 Storybook 配置文件中删除现有的 managerWebpack 配置元素，并将图像或 CSS 以外的资源预先捆绑到 JavaScript 中。

Storybook 不使用 Webpack 4 运行

已删除对 Webpack 4 的支持，并且不再维护。如果您要升级 Storybook，它将自动使用 Webpack 5 并尝试迁移您的配置。但是，如果您正在使用自定义 Webpack 配置，则可能需要更新它以使其与 Webpack 5 兼容。迁移过程对于确保您的项目在最新版本的 Storybook 上顺利运行是必要的。您可以按照 Webpack 网站上提供的说明更新您的配置。

了解有关构建器的更多信息

Vite 构建器，用于与 Vite 捆绑
Webpack 构建器，用于与 Webpack 捆绑
构建器 API，用于构建 Storybook 构建器