Vite

Storybook Vite 构建器使用 Vite（一个快速的 ESM 打包器）打包你的组件和故事。

对于使用 Vite 构建的应用程序：它允许在 Storybook 中复用现有配置。
对于使用 Webpack 构建的应用程序：它提供了更快的启动和刷新时间，但缺点是组件的执行环境与应用程序不同。

设置

如果你在你的 Vite 应用程序中运行了 npx storybook@latest init 来包含 Storybook，那么构建器已经为你安装和配置。如果你需要，也可以手动选择它。

运行以下命令来安装构建器。

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

更新你的 Storybook 配置（在 .storybook/main.js|ts 中）以包含构建器。

.storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite', // 👈 The builder enabled here.
  },
};

配置

默认情况下，Storybook 的 Vite 构建器包含一组支持框架的默认配置，这些配置将与你现有的配置文件合并。为了在使用 Vite 构建器时获得最佳体验，我们建议将所有配置直接应用到 Vite 的配置文件中（即 vite.config.js|ts）。

Storybook 加载时会自动将配置合并到自己的配置中。但是，由于不同的项目可能会有特定的需求，你可能需要为 Storybook 提供自定义配置。在这种情况下，你可以修改配置文件 (.storybook/main.js|ts) 并添加 viteFinal 配置函数，如下所示

.storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config) {
    // Merge custom configuration into the default config
    const { mergeConfig } = await import('vite');
 
    return mergeConfig(config, {
      // Add dependencies to pre-optimization
      optimizeDeps: {
        include: ['storybook-dark-mode'],
      },
    });
  },
};

异步函数 viteFinal 会接收一个带有默认构建器配置的 config 对象，并返回更新后的配置。

基于环境的配置

如果你需要自定义构建器的配置并根据你的环境应用特定选项，请扩展 viteFinal 函数，如下所示

.storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: '@storybook/builder-vite',
  },
  async viteFinal(config, { configType }) {
    const { mergeConfig } = await import('vite');
 
    if (configType === 'DEVELOPMENT') {
      // Your development configuration goes here
    }
    if (configType === 'PRODUCTION') {
      // Your production configuration goes here.
    }
    return mergeConfig(config, {
      // Your environment configuration here
    });
  },
};

覆盖默认配置

默认情况下，Storybook 中的 Vite 构建器会在你的 Storybook 项目的根目录中搜索 Vite 配置文件。但是，你可以自定义它，使其在另一个位置查找配置文件。例如

.storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  core: {
    builder: {
      name: '@storybook/builder-vite',
      options: {
        viteConfigPath: '../customVite.config.js',
      },
    },
  },
};

如果你不希望 Storybook 自动加载 Vite 配置文件，可以使用 viteConfigPath 选项指向一个不存在的文件。

TypeScript

如果你需要，也可以使用 TypeScript 配置 Storybook 的 Vite 构建器。将你的 .storybook/main.js 重命名为 .storybook/main.ts 并进行如下调整

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-vite, 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)'],
  async viteFinal(config, options) {
    // Add your configuration here
    return config;
  },
};
 
export default config;

故障排除

工作目录未检测到

默认情况下，Vite 构建器会为提高安全性而启用 Vite 的 server.fs.strict 选项，将项目的 root 定义为 Storybook 的配置文件目录。如果需要覆盖它，可以使用 viteFinal 函数并进行调整。

目前，自动 ArgType 推断仅适用于 React、Vue 3 和 Svelte（仅 JSDocs）。对于 React，Vite 构建器默认使用 react-docgen，它是一种比 react-docgen-typescript 更快的解析 React 组件的替代方案。如果遇到任何问题，可以通过更新 Storybook 配置文件来恢复到 react-docgen-typescript，如下所示

.storybook/main.js|ts

export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-essentials'],
  core: {
    builder: '@storybook/builder-vite',
  },
  typescript: {
    // Enables the `react-docgen-typescript` parser.
    // See https://storybook.org.cn/docs/api/main-config/main-config-typescript for more information about this option.
    reactDocgen: 'react-docgen-typescript',
  },
};

组件测试无法按预期工作

如果您从基于 Webpack 的项目（如 CRA）迁移到 Vite，并且已使用 @storybook/addon-interactions 加载项启用组件测试，您可能会遇到测试无法执行的情况，通知您 window 对象未定义。要解决此问题，可以在 Storybook 配置目录中创建一个 preview-head.html 文件，并包含以下内容

{/* .storybook/preview-head.html */}
 
<script>
  window.global = window;
</script>

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

Vite 构建器，用于使用 Vite 进行捆绑
Webpack 构建器，用于使用 Webpack 进行捆绑
构建器 API，用于构建 Storybook 构建器