Vite

Storybook Vite 建構器使用快速的 ESM 捆綁器 Vite 捆綁您的元件和 story。

對於使用 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;

疑難排解

偵測不到工作目錄

預設情況下，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.dev.org.tw/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 建構器
用於建立 Storybook 建構器的建構器 API