Vite

Storybook Vite 构建器使用 Vite，一个快速的 ESM 构建器，来构建你的组件和故事。

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

设置

如果你运行了 npx storybook@latest init 来将 Storybook 添加到你的 Vite 应用程序中，那么构建器已经被安装和配置好了。如果你愿意，也可以手动进行配置。

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

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

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

.storybook/main.ts

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

配置

Storybook 的 Vite 构建器开箱即用地提供了支持框架的默认配置集，这些配置会与你现有的配置文件合并。为了在使用 Vite 构建器时获得最佳体验，我们建议直接在 Vite 的配置文件（即 vite.config.js|ts）中进行任何配置。

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

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  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'],
      },
    });
  },
};
 
export default config;

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

基于环境的配置

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

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  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
    });
  },
};
 
export default config;

覆盖默认配置

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

.storybook/main.ts

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

如果你不想让 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, nextjs-vite, vue3-vite, etc.
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 组件比 react-docgen-typescript 更快的替代方案。如果遇到任何问题，可以通过更新 Storybook 配置文件来恢复到 react-docgen-typescript，如下所示

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  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',
  },
};
 
export default config;

交互测试未按预期工作

如果你正在从基于 Webpack 的项目（如 CRA）迁移到 Vite，并且你正在进行交互测试，你可能会遇到测试执行失败并提示 window 对象未定义的情况。要解决此问题，可以在 Storybook 配置目录中创建一个 preview-head.html 文件并包含以下内容

.storybook/preview-head.html

<script>
  window.global = window;
</script>

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

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