manifest.json 出發,為 Chrome、Edge、Firefox 與 Safari 建置並執行瀏覽器擴充功能。它在所有擴充功能情境下都能執行 TypeScript:background、content script、popup、options 與 sidebar。它預設使用 Rspack + SWC pipeline。你不需要額外的 tsc 步驟、ts-loader 或額外的 bundler rule。
建置完全不需要 typescript 套件。SWC 會編譯你的原始碼並移除型別。這個套件只對編輯器工具與 tsc --noEmit 型別檢查有意義。也因此,缺少 typescript 套件永遠不會讓建置失敗,這一點和缺少框架整合套件不同。
什麼情況下適合使用 TypeScript
- 你希望在擴充功能各情境之間有更安全的重構與更明確的介面。
- 你會在 background script、content script 與 UI 介面之間共用邏輯。
- 你需要在使用 AI 產生程式碼時,仍能取得可預期的 API 使用方式。
範本範例
new-typescript

content-typescript

自動產生的 ambient 型別
對於 TypeScript 專案,Extension.js 會在你的專案根目錄產生extension-env.d.ts 檔,包含 ambient 宣告(browser/runtime 全域、EXTENSION_PUBLIC_* 環境變數,以及打包工具型別)。dev、build 與 start 都會重新產生它,因此編輯器型別與 CI 上的 tsc --noEmit 會保持同步。可以把它納入版本控管或加入 git ignore,兩種方式都可以,下一次執行時會重新建立。
從 4.1.39 之後的版本起,這個檔案不存在時,只有在你的 tsconfig.json 會讀到它的情況下才會被建立。見讓 extension-env.d.ts 留在 include 清單裡。
在既有擴充功能中使用
依下列步驟把 TypeScript 加入既有擴充功能。安裝
- 將 TypeScript 安裝為 development dependency:
- 初始化 TypeScript 設定檔
tsconfig.json:
設定
TypeScript 偵測與需求
Extension.js 會在package.json 旁邊尋找 tsconfig.json。
- 沒有
tsconfig.json的專案,只要建置會編譯到 TypeScript,就會得到一份基準設定:manifest 指明的指令碼、頁面載入的指令碼,或是它們透過相對路徑匯入的檔案。建置會顯示Creating a default tsconfig.json並繼續進行。 - 沒有任何地方載入的
.ts檔案不算,單獨宣告typescript相依套件也不算。從 4.1.41 之後的版本開始,建置不會在這樣的專案中寫入任何檔案。
moduleResolution是bundler,對應 Rspack + SWC pipeline。已被移除的node(node10)模式會讓 TypeScript 7 上的tsc --noEmit失敗。- 從 4.1.41 之後的版本起,
moduleDetection是force,範本也設定了它。bundler 把每個檔案都當成模組,所以tsc也一樣。少了它,沒有import的指令稿會是全域指令稿,頂層的const status會因為 DOM 型別中已經有status而以 TS2451 失敗。請把這一行加到較舊的tsconfig.json。 - 只有當 Extension.js 在專案中偵測到 JSX 框架時,
jsx才會是react-jsx。沒有偵測到時,它會維持preserve,也不會寫入jsxImportSource。從 4.1.20 起,框架專案還會得到jsxImportSource,依偵測到的框架設為react、preact、vue或solid-js,這樣tsc --noEmit解析的 JSX 執行階段與建置一致。
自動型別
Extension.js 會在專案根目錄產生extension-env.d.ts。dev、build 與 start 每次都會重寫它。這個檔案引用擴充功能 API、Extension.js 環境變數鍵與資源匯入的型別宣告。
extension-env.d.ts
擴充功能 API 的型別
Extension.js 用chrome-types 為擴充功能 API 提供型別。這個套件由 Chrome 從 Chromium 原始碼產生。browser 是原生 namespace,它的方法回傳 Promise。chrome 是它的別名。這個套件隨 extension 一起安裝,所以新專案不需要額外的型別套件。
chrome-types 沒有宣告只有 Firefox 才有的 API。Firefox 的 browser.sidebarAction 與 browser.browserAction 由 Extension.js 自己提供型別。
從 4.1.40 之後的版本起,Extension.js 還在 chrome-types 之上補充了三項內容,讓瀏覽器接受的程式碼能夠通過型別檢查:
- 緊接在你傳入的引數之後的回呼,例如
chrome.tabs.sendMessage(tabId, message, callback)。單獨使用chrome-types時,回呼只有放在所有選用引數之後才有型別。 - Chrome 在執行階段提供的列舉物件,例如
chrome.runtime.OnInstalledReason.INSTALL。這些是 Chrome 的物件。Firefox 提供的較少,部分鍵名也不同,所以同時支援兩個瀏覽器的程式碼應該直接比較字串,例如reason === 'install'。 chrome.tabs.OnUpdatedInfo,也可以寫成chrome.tabs.TabChangeInfo,用於tabs.onUpdated的變更引數。
new chrome.declarativeContent.ShowAction() 會提示缺少引數。請寫成 new chrome.declarativeContent.ShowAction({}),Chrome 對兩者的處理相同。
安裝了 @types/chrome 的專案
安裝了@types/chrome 的專案會繼續使用它。chrome 的型別來自這個套件,browser 的型別和以前一樣來自 webextension-polyfill。
@types/chrome 與 chrome-types 都宣告了 chrome 全域變數,所以這兩個套件不能同時載入。產生的 extension-env.d.ts 只引用其中一個。當你的 package.json 列出了 @types/chrome 時,它引用 @types/chrome:
extension-env.d.ts
node_modules 裡有、但你的 package.json 沒有列出的副本(例如提升到工作區根目錄的副本),只對使用 TypeScript 5 或更早版本的專案生效。TypeScript 6 及更新版本不會載入專案沒有引用的 @types 套件,所以使用 TypeScript 6 或更新版本、又想用 @types/chrome 的工作區專案,要在自己的 package.json 裡列出它。較早的版本只要專案資料夾或某個上層資料夾裡存在 node_modules/@types/chrome,就會引用 @types/chrome。
改用 chrome-types:
- 從專案裡移除
@types/chrome。 - 執行一次
extension dev或extension build。
@types/chrome:
- 把
@types/chrome安裝為開發相依套件。 - 執行一次
extension dev或extension build。
Polyfill 的型別
在預設設定下,browser 全域變數擁有來自 chrome-types 的原生型別。想要 webextension-polyfill 的型別,請匯入這個模組:
升級說明
更早的版本會隨extension 一起安裝 @types/chrome,並用 webextension-polyfill 為 browser 提供型別。安裝了 @types/chrome 的專案會保留這些型別。沒有 @types/chrome 的專案在升級後會改用 chrome-types。
改用之後,tsc 可能會回報 chrome.tabs.TabChangeInfo 這樣的名稱不存在。安裝 @types/chrome 可以保留以前的型別,然後執行一次 extension dev 或 extension build。
轉譯與型別檢查的差別
預設的打包 pipeline 會編譯 TypeScript,但不會在打包過程中執行完整的tsc 型別檢查。
建議的 scripts:
tsc 不會寫出 extension-env.d.ts。只有 dev、build 與 start 會重新產生它。在 CI 中,請先執行其中一個指令,再執行 tsc:
下一步
- 了解 Extension.js 如何處理 ECMAScript modules。
- 探索 Sass modules 等樣式選項。
- 閱讀 瀏覽器擴充功能中的 JavaScript 與 TypeScript 檔案。
- 比較各個 瀏覽器擴充功能框架 對 TypeScript 的支援。

