Vite

Storybook Vite 构建工具使用 Vite（一个快速的 ESM 打包器）来打包你的组件和 stories。

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

设置

如果你运行了 npx storybook@latest init 将 Storybook 包含在你的 Vite 应用程序中，构建工具已经为你安装和配置好了。如果你愿意，你也可以手动选择它。

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

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;

故障排除

从 Webpack 迁移

Vite 通常比 Webpack 更能开箱即用地处理更多用例。例如，加载样式对于大多数项目来说都可以正常工作。因此，当将基于 Webpack 的项目迁移到 Vite 时，你可能会发现你不需要之前的所有配置。

我们建议从没有 Storybook 特定的 Vite 配置开始，只添加你确定你的项目实际需要的内容。

作为参考，这是一个 Webpack 配置，用于处理加载 graphql 查询，以及其在 Vite 中的等效配置（使用插件）

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, nextjs, angular)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  async webpackFinal(config) {
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/emails')],
      exclude: /node_modules/,
      loader: 'graphql-tag/loader',
    });
    config.module?.rules?.push({
      test: /\.(graphql|gql)$/,
      include: [path.resolve('./lib/schema')],
      exclude: /node_modules/,
      loader: 'raw-loader',
    });
 
    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>

了解更多关于构建工具的信息