Vite

Storybook Vite 建構工具使用快速的 ESM 打包工具 Vite 來打包您的元件和 stories。

對於使用 Vite 建構的應用程式：它允許在 Storybook 中重複使用現有的設定。
對於使用 Webpack 建構的應用程式：它提供更快的啟動和重新整理時間，缺點是您元件的執行環境與您的應用程式不同。

設定

如果您執行了 npx storybook@latest init 以在您的 Vite 應用程式中包含 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;

疑難排解

從 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 元件。如果您遇到任何問題，您可以還原為 react-docgen-typescript，方法是更新您的 Storybook 設定檔，如下所示

.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 打包
建構工具 API，用於建構 Storybook 建構工具