Webpack

Storybook Webpack 建構器是 Storybook 的預設建構器。此建構器讓您能夠為您的元件建立無縫的開發和測試體驗，並提供有效率的方式來獨立開發 UI 元件，讓您能夠將現有的 Webpack 配置與 Storybook 結合使用。

設定

預設情況下，Storybook 為 Webpack 提供零配置支援，並自動設定基準配置，以適用於最常見的使用案例。但是，您可以擴充 Storybook 的設定檔 (即 .storybook/main.js|ts)，並提供其他選項來提升 Storybook 的效能或根據您的需求進行自訂。以下列出可用的選項以及如何使用它們的範例。

選項	描述
`lazyCompilation`	啟用 Webpack 的實驗性 `lazy compilation` `core: { builder: { options: { lazyCompilation: true } } }`
`fsCache`	配置 Webpack 的檔案系統快取功能 `core: { builder: { options: { fsCache: true } } }`

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, 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)'],
  core: {
    builder: {
      name: '@storybook/builder-webpack5',
      options: {
        fsCache: true,
        lazyCompilation: true,
      },
    },
  },
};
 
export default config;

覆寫預設配置

Storybook 的 Webpack 配置基於 Webpack 5，使其可以擴充以符合您的專案需求。如果您需要新增 loader 或 plugin，您可以在 .storybook/main.js|ts 檔案中提供 webpackFinal 配置元素。此配置元素應匯出一個函式，該函式接收基準配置作為第一個參數，以及 Storybook 的選項物件作為第二個參數。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, 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)'],
  webpackFinal: async (config, { configType }) => {
    if (configType === 'DEVELOPMENT') {
      // Modify config for development
    }
    if (configType === 'PRODUCTION') {
      // Modify config for production
    }
    return config;
  },
};
 
export default config;

當 Storybook 啟動時，它會自動將配置合併到其自身。但是，當提供 webpackFinal 配置元素時，您有責任自行合併配置。我們建議您負責任地處理對 config 物件的變更，並保留 entry 和 output 屬性。

使用 Webpack plugins

自訂 Storybook 配置的另一種方法是新增自訂 plugin 或 loader，以協助程式碼最佳化、資產管理或其他任務。儘管如此，由於 Storybook 依賴 HtmlWebpackPlugin 來產生預覽頁面，我們建議您將變更附加到 config.plugins 陣列，而不是覆寫它。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, 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)'],
  webpackFinal: async (config) => {
    config.plugins.push(/* ... */);
    return config;
  },
};
 
export default config;

此外，當使用未明確包含特定檔案副檔名 (即透過 test 屬性) 的 Webpack loaders 時，您應該為該 loader 排除 .ejs 檔案副檔名。

導入自訂 Webpack 配置

如果您已經有現有的 Webpack 配置檔需要與 Storybook 重複使用，您可以導入它並將其合併到預設配置中。例如

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import custom from '../webpack.config.js'; // 👈 Custom Webpack configuration being imported.
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    return {
      ...config,
      module: { ...config.module, rules: [...config.module.rules, ...custom.module.rules] },
    };
  },
};
 
export default config;

基於產生器 scaffold 的專案可能需要您導入其特定的 Webpack 配置檔。我們建議您閱讀產生器的文件以取得更多資訊。

Debug Webpack 配置

如果您打算 debug Storybook 使用的 Webpack 配置，可以使用 Storybook CLI 來協助您。如果您在開發模式下執行，可以使用以下命令

npm run storybook -- --debug-webpack

此外，如果您正在產生 Storybook 的靜態 build，可以使用以下命令

npm run build-storybook -- --debug-webpack

編譯器支援

Storybook 採用與編譯器無關的方法進行打包。這讓您可以攜帶自己的應用程式打包器 (例如 Babel、SWC)，並確保在基於 Webpack 5 的專案的龐大生態系統中的相容性。

SWC

如果您的專案是使用 SWC 建置的，請使用 @storybook/addon-webpack5-compiler-swc 附加元件。此附加元件提高了與 Webpack 5 專案的生態系統相容性，同時保持了高效能。執行以下命令以自動設定附加元件

npx storybook@latest add @storybook/addon-webpack5-compiler-swc

可以提供其他選項來自訂 SWC 配置。有關更多資訊，請參閱SWC API 文件。

啟用後，此附加元件會調整 Webpack 配置，以使用 swc-loader 處理 JavaScript 和 TypeScript 檔案。此外，它將偵測並使用您專案的 SWC 配置。

Babel

如果您正在處理依賴 Babel 工具來提供特定功能 (包括 TypeScript 或其他現代 JavaScript 功能) 支援的專案，可以使用 @storybook/addon-webpack5-compiler-babel 附加元件，讓您將它們包含在 Storybook 中，以確保與您的專案相容。執行以下命令以自動設定附加元件

npx storybook@latest add @storybook/addon-webpack5-compiler-babel

可以提供其他選項來自訂 Babel 配置。有關更多資訊，請參閱 babel API 文件，或者如果您正在開發附加元件，請參閱 babelDefault 文件以取得更多資訊。

啟用後，此附加元件會調整 Webpack 配置，以使用 babel-loader 作為 JavaScript 和 TypeScript 檔案的預設 loader。此外，它將偵測並使用您專案的 Babel 配置。

Storybook 的預設 Webpack 配置為大多數專案設定提供支援，而無需任何額外配置。儘管如此，根據您的專案配置或選擇的框架，當從您的 tsconfig file 中設定別名時，您可能會遇到 TypeScript 模組在 Storybook 中無法解析的問題。如果您遇到此問題，可以使用 tsconfig-paths-webpack-plugin，同時擴充 Storybook 的 Webpack 配置，如下所示

.storybook/main.ts

// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
import TsconfigPathsPlugin from 'tsconfig-paths-webpack-plugin';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.plugins = [
        ...(config.resolve.plugins || []),
        new TsconfigPathsPlugin({
          extensions: config.resolve.extensions,
        }),
      ];
    }
    return config;
  },
};
 
export default config;

但是，如果您正在使用提供預設別名配置的框架 (例如 Next.js、Nuxt)，並且想要設定 Storybook 使用相同的別名，則可能不需要安裝任何額外套件。相反地，您可以擴充 Storybook 的預設配置，以使用框架提供的相同別名。例如，若要為 @ 導入路徑設定別名，您可以將以下內容新增至您的 .storybook/main.js|ts 檔案

.storybook/main.ts

import path from 'path';
// Replace your-framework with the framework you are using (e.g., react-webpack5, vue3-vite)
import type { StorybookConfig } from '@storybook/your-framework';
 
const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|ts|tsx)'],
  webpackFinal: async (config) => {
    if (config.resolve) {
      config.resolve.alias = {
        ...config.resolve.alias,
        '@': path.resolve(__dirname, '../src'),
      };
    }
    return config;
  },
};
 
export default config;

預先打包的資產未顯示在 Storybook UI 中

由於 Storybook 依賴 esbuild 來建置其內部管理器，因此使用 managerWebpack 打包資產的支援將不再對 Storybook UI 產生影響。我們建議從您的 Storybook 設定檔中移除現有的 managerWebpack 配置元素，並預先將圖片或 CSS 以外的資產打包到 JavaScript 中。

Storybook 無法與 Webpack 4 一起執行

Webpack 4 的支援已移除，且不再維護。如果您正在升級 Storybook，它將自動使用 Webpack 5 並嘗試遷移您的配置。但是，如果您正在使用自訂 Webpack 配置，可能需要更新它以與 Webpack 5 搭配使用。遷移過程是必要的，以確保您的專案在最新版本的 Storybook 上順利執行。您可以按照 Webpack 網站上提供的指示來更新您的配置。

深入了解建構器