The cross-browser extension framework

在不離開 Extension.js 工作流程的前提下自訂打包行為。不必分叉預設設定就能解決自訂 bundler 需求。可以直接加上 loader（檔案型態轉換）、plugin（建置時擴充）與別名（import 捷徑）。Extension.js 使用 Rspack（基於 Rust 的 JavaScript bundler，@rspack/core）建置，你可以直接擴充產生出的設定。

運作方式

在專案根目錄建立下列其中一個檔案：

extension.config.js
extension.config.mjs
extension.config.cjs

使用 config 鍵來修補產生出的 bundler 設定。

`config` 能力

能力	作用
函式 hook（`config: (config) => config`）	在建置前讀取並修改產生的 Rspack 設定，擁有完整控制權。
物件合併（`config: { ... }`）	把額外設定合併進產生的基底設定。
Rules（`config.module.rules`）	為檔案型態新增或調整 loader 規則。
Plugins（`config.plugins`）	加入編譯時的 plugin 與轉換。
Resolve（`config.resolve`）	加入別名與模組解析行為。

選項一：函式 hook（建議）

export default {
  config: (config) => {
    config.module.rules.push({
      test: /\.mdx$/,
      use: ["babel-loader", "@mdx-js/loader"],
    });
    return config;
  },
};

選項二：物件合併

config 也可以是物件，Extension.js 會把它合併進基底設定。

export default {
  config: {
    resolve: {
      alias: {
        "@ui": "/absolute/path/to/ui",
      },
    },
  },
};

Rspack 優先，相容 webpack

Extension.js 原生使用 Rspack，但你仍可使用大部分 webpack 生態系。

設定型別擴充自 @rspack/core 的 Configuration。
許多 webpack loader／plugin 透過相容層可運作。
部分 webpack 內部／plugin 與 Rspack 並非完全 1:1 相容。

使用 Rspack 原生 plugin 的範例：

import { DefinePlugin } from "@rspack/core";

export default {
  config: (config) => {
    config.plugins = [
      ...config.plugins,
      new DefinePlugin({
        __FEATURE_FLAG__: JSON.stringify("enabled"),
      }),
    ];
    return config;
  },
};

何時使用

為專案特定的檔案型態加入自訂 loader／規則。
加入用於編譯時轉換與診斷的 plugin。
覆寫 Extension.js 一級選項未提供的解析別名與模組行為。

最佳實務

優先使用一級選項：先嘗試 browser / commands 設定鍵，再考慮底層 bundler 覆寫。
最小化修補：只更動需要的部分，然後回傳設定。
plugin 保持 Rspack 友善：可用 Rspack 原生 plugin 時優先使用。
在所有目標驗證：設定變更後，針對你的瀏覽器矩陣測試 dev、start、preview 與 build。

下一步

進一步了解 extension 設定（extension.config.js）。
進一步了解多平台建置。

Extension 設定（extension.config.js）頁面重新載入與 hot module replacement（HMR）

​運作方式

​config 能力

​選項一：函式 hook（建議）

​選項二：物件合併

​Rspack 優先，相容 webpack

​何時使用

​最佳實務

​下一步