> ## Documentation Index
> Fetch the complete documentation index at: https://extension.js.org/llms.txt
> Use this file to discover all available pages before exploring further.

# 在 extension.config.js 中設定 Rspack

> 透過 extension.config.js 加上 loader、plugin 與別名來自訂 Rspack 打包，不必分叉 Extension.js 的預設建置設定。

在不離開 Extension.js 工作流程的前提下自訂打包行為。

不必分叉預設設定就能解決自訂 bundler 需求。可以直接加上 loader（檔案型態轉換）、plugin（建置時擴充）與別名（import 捷徑）。Extension.js 使用 [Rspack](https://rspack.dev)（基於 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（建議）

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

### 選項二：物件合併

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

```js theme={null}
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 的範例：

```js theme={null}
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`）](/docs/features/extension-configuration)。
* 進一步了解 [多平台建置](/docs/features/multi-platform-builds)。