Docs
Storybook Docs

Vite

Storybook Vite 构建器将你的组件和故事与快速 ESM 打包器 Vite 打包在一起。

¥Storybook Vite builder bundles your components and stories with Vite, a fast ESM bundler.

  • 对于使用 Vite 构建的应用：它允许重用 Storybook 中的现有配置。

    ¥For applications built with Vite: it allows reusing the existing configuration in Storybook.

  • 对于使用 Webpack 构建的应用：它提供更快的启动和刷新时间，但缺点是组件的执行环境与你的应用不同。

    ¥For applications built with Webpack: it provides faster startup and refresh times, with the disadvantage that your component's execution environment differs from your application.

设置

¥Setup

如果你运行 npx storybook@latest init 以将 Storybook 包含在你的 Vite 应用中，则构建器已经为你安装和配置。如果你愿意，你也可以手动选择加入。

¥If you ran npx storybook@latest init to include Storybook in your Vite application, the builder is already installed and configured for you. If you want, you can also opt into it manually.

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

¥Run the following command to install the builder.

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

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

¥Update your Storybook configuration (in .storybook/main.js|ts) to include the builder.

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

配置

¥Configuration

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

¥Out of the box, Storybook's Vite builder includes a set of configuration defaults for the supported frameworks, which are merged alongside your existing configuration file. For an optimal experience when using the Vite builder, we recommend applying any configuration directly inside Vite's configuration file (i.e., vite.config.js|ts).

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

¥When Storybook loads, it automatically merges the configuration into its own. However, since different projects may have specific requirements, you may need to provide a custom configuration for Storybook. In such cases, you can modify your configuration file (.storybook/main.js|ts) and add the viteFinal configuration function as follows:

.storybook/main.js|ts
export default {
  stories: ['../src/**/*.mdx', '../stories/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: ['@storybook/addon-links', '@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 对象并返回更新后的配置。

¥The asynchronous function viteFinal receives a config object with the default builder configuration and returns the updated configuration.

基于环境的配置

¥Environment-based configuration

如果你需要自定义构建器的配置并根据你的环境应用特定选项，请按如下方式扩展 viteFinal 功能：

¥If you need to customize the builder's configuration and apply specific options based on your environment, extend the viteFinal function as follows:

.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
    });
  },
};

覆盖默认配置

¥Override the default configuration

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

¥By default, the Vite builder in Storybook searches for the Vite configuration file in the root directory of your Storybook project. However, you can customize it to look for the configuration file in a different location. For example:

.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 选项指向不存在的文件。

¥If you do not want Storybook to load the Vite configuration file automatically, you can use the viteConfigPath option to point to a non-existent file.

TypeScript

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

¥If you need, you can also configure Storybook's Vite builder using TypeScript. Rename your .storybook/main.js to .storybook/main.ts and adjust it as follows:

.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;

故障排除

¥Troubleshooting

未检测到工作目录

¥Working directory not being detected

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

¥By default, the Vite builder enables Vite's server.fs.strict option for increased security, defining the project's root to Storybook's configuration directory. If you need to override it, you can use the viteFinal function and adjust it.

ArgType 不会自动生成

¥ArgTypes are not generated automatically

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

¥Currently, automatic argType inference is only available for React, Vue 3, and Svelte (JSDocs only). With React, the Vite builder defaults to react-docgen, a faster alternative to react-docgen-typescript for parsing React components. If you run into any issues, you can revert to react-docgen-typescript by updating your Storybook configuration file as follows:

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

组件测试未按预期工作

¥Component tests not working as expected

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

¥If you are migrating from a Webpack-based project, such as CRA, to Vite, and you have enabled component testing with the @storybook/addon-interactions addon, you may run into a situation where your tests fail to execute notifying you that the window object is not defined. To resolve this issue, you can create a preview-head.html file in your Storybook configuration directory and include the following:

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

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

¥Learn more about builders