feat: Add @wxt-dev/webextension-polyfill module (#1310)

.github/workflows/release.yml

@@ -15,6 +15,7 @@ on:
           - module-vue
           - storage
           - unocss
+          - webextension-polyfill
           - wxt
 
 jobs:

.github/workflows/sync-releases.yml

@@ -14,6 +14,7 @@ on:
           - module-svelte
           - module-vue
           - storage
+          - webextension-polyfill
           - wxt
 
 jobs:

docs/guide/resources/upgrading.md

@@ -31,12 +31,11 @@ WXT no longer uses the `webextension-polyfill` internally and `wxt/browser` uses
 To upgrade, you have two options:
 
 1. **Stop using the polyfill**
-   - No changes required, this is the default behavior of v0.20. Your extension will likely continue to work, but do some manual testing to confirm.
+   - Replace any manual imports from `wxt/browser/chrome` with `wxt/browser`
 2. **Continue using the polyfill**
-   - Install the polyfill, types (if you use typescript), and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill):
+   - Install the polyfill and WXT's [new polyfill module](https://www.npmjs.com/package/@wxt-dev/webextension-polyfill):
      ```sh
-     pnpm i webextension-polyfill
-     pnpm i -D @types/webextension-polyfill @wxt-dev/webextension-polyfill
+     pnpm i webextension-polyfill @wxt-dev/webextension-polyfill
      ```
    - Add the WXT module to your config:
      ```ts
@@ -46,7 +45,7 @@ To upgrade, you have two options:
      });
      ```
 
-Additionally, the `extensionApi` config has been removed. Remove it from your `wxt.config.ts` file if present:
+Regardless of your choice, the `extensionApi` config has been removed. Remove it from your `wxt.config.ts` file if present:
 
 ```ts
 // wxt.config.ts
@@ -55,6 +54,21 @@ export default defineConfig({
 });
 ```
 
+Additionally, extension API types have changed. `wxt/browser` now uses types from `@types/chrome` instead of `@types/webextension-polyfill`. You will have to migrate any type imports to use `@types/chrome`'s namespace approach:
+
+<!-- prettier-ignore -->
+```ts
+import type { Runtime } from 'wxt/browser'; // [!code --]
+import { browser } from 'wxt/browser'; // [!code ++]
+
+function getMessageSenderUrl(sender: Runtime.MessageSender): string { // [!code --]
+function getMessageSenderUrl(sender: browser.runtime.MessageSender): string { // [!code ++]
+  // ...
+}
+```
+
+`@types/chrome` are more up-to-date, contain less bugs, and don't have any auto-generated names. So even if you continue to use the polyfill, you will need to update your types to use these types.
+
 ### `public/` and `modules/` Directories Moved
 
 The default location for the `public/` and `modules/` directories have changed to better align with standards set by other frameworks (Nuxt, Next, Astro, etc). Now, each path is relative to the project's root directory.

packages/webextension-polyfill/README.md

@@ -0,0 +1,18 @@
+# `@wxt-dev/webextension-polyfill`
+
+Configures `wxt/browser` to import `browser` from [`webextension-polyfill`](https://github.com/mozilla/webextension-polyfill) instead of using the regular `chrome`/`browser` globals WXT normally provides.
+
+## Usage
+
+```sh
+pnpm i @wxt-dev/webextension-polyfill webextension-polyfill
+```
+
+Then add the module to your config:
+
+```ts
+// wxt.config.ts
+export default defineConfig({
+  modules: ['@wxt-dev/webextension-polyfill'],
+});
+```

packages/webextension-polyfill/build.config.ts

@@ -0,0 +1,15 @@
+import { defineBuildConfig } from 'unbuild';
+import { resolve } from 'node:path';
+
+export default defineBuildConfig({
+  rootDir: 'modules',
+  outDir: resolve(__dirname, 'dist'),
+  entries: [
+    { input: 'webextension-polyfill/index.ts', name: 'index' },
+    { input: 'webextension-polyfill/browser.ts', name: 'browser' },
+  ],
+  replace: {
+    'process.env.NPM': 'true',
+  },
+  declaration: true,
+});

packages/webextension-polyfill/entrypoints/content/index.ts

@@ -0,0 +1,6 @@
+export default defineContentScript({
+  matches: ['*://*/*'],
+  async main() {
+    console.log(browser.runtime.id);
+  },
+});

packages/webextension-polyfill/entrypoints/popup/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>Document</title>
+  </head>
+  <body>
+    <div id="app"></div>
+    <script type="module" src="./main.ts"></script>
+  </body>
+</html>

packages/webextension-polyfill/entrypoints/popup/main.ts

@@ -0,0 +1,3 @@
+const root = document.getElementById('app')!;
+
+root.textContent = browser.runtime.id;

packages/webextension-polyfill/modules/webextension-polyfill/browser.ts

@@ -0,0 +1 @@
+export { default as browser } from 'webextension-polyfill';

packages/webextension-polyfill/modules/webextension-polyfill/index.ts

@@ -0,0 +1,18 @@
+import 'wxt';
+import { addViteConfig, defineWxtModule } from 'wxt/modules';
+import { resolve } from 'node:path';
+
+export default defineWxtModule({
+  name: '@wxt-dev/webextension-polyfill',
+  setup(wxt) {
+    addViteConfig(wxt, () => ({
+      resolve: {
+        alias: {
+          'wxt/browser': process.env.NPM
+            ? '@wxt-dev/webextension-polyfill/browser'
+            : resolve(__dirname, 'browser.ts'),
+        },
+      },
+    }));
+  },
+});

packages/webextension-polyfill/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "@wxt-dev/webextension-polyfill",
+  "description": "Use webextension-polyfill with WXT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/wxt-dev/wxt.git",
+    "directory": "packages/webextension-polyfill"
+  },
+  "homepage": "https://github.com/wxt-dev/wxt/blob/main/packages/webextension-polyfill/README.md",
+  "keywords": [
+    "wxt",
+    "module",
+    "webextension-polyfill"
+  ],
+  "author": {
+    "name": "Aaron Klinker",
+    "email": "[email protected]"
+  },
+  "license": "MIT",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./browser": {
+      "types": "./dist/browser.d.mts",
+      "default": "./dist/browser.mjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "dev": "wxt",
+    "check": "pnpm build && check",
+    "build": "buildc -- unbuild",
+    "prepare": "buildc --deps-only -- wxt prepare"
+  },
+  "peerDependencies": {
+    "webextension-polyfill": "*",
+    "wxt": ">=0.20.0"
+  },
+  "devDependencies": {
+    "@aklinker1/check": "^1.4.5",
+    "@types/webextension-polyfill": "^0.12.1",
+    "publint": "^0.2.12",
+    "typescript": "^5.6.3",
+    "unbuild": "^2.0.0",
+    "webextension-polyfill": "^0.12.0",
+    "wxt": "workspace:*"
+  }
+}

packages/webextension-polyfill/tsconfig.json

@@ -0,0 +1,4 @@
+{
+  "extends": ["../../tsconfig.base.json", "./.wxt/tsconfig.json"],
+  "exclude": ["node_modules/**", "dist/**"]
+}