[Experimental Feedback] Exclude webextension-polyfill via extensionApi: "chrome"

[aklinker1]

v0.19.0 introduced a new option for excluding the webextension-polyfill.

Setup

1. Update your wxt.config.ts with the new feature flag:

   export default defineConfig({
     extensionApi: "chrome"
   })

2. Install @types/chrome, the package providing types when using the chrome API. It provides more up-to-date types with much better support for MV3 features.

   $ pnpm i -D @types/chrome

3. Regenerate project types:

   $ pnpm wxt prepare

4. (Optional) Restart your editor or language server so your editor is using the new types
5. (Optional) Ignore this step if you're using auto-imports. If you've disabled auto-imports, you'll need to update all your browser imports.

   If you skip this step, everything should still work, but your editor will continue using the old types instead of @types/chrome.

   - import { browser } from 'wxt/browser';
   + import { browser } from 'wxt/browser/chrome';

Testing

• Are there any type errors? (Remember to run wxt prepare before this)
• Any runtime errors in dev mode?

  $ wxt

• Any runtime errors when loading production builds?

  $ wxt zip

• If you're supporting Firefox/Safari, are there any runtime errors when ran there?

---

Note

If you have any feedback, problems, type errors, or runtime issues, please share them below so I can get them fixed. Goal is to ship this option as the default in the next major version, v0.20.0

[aiktb]

import type { Commands } from "wxt/browser";

Is there a way to make code like this take advantage of the types in @types/chrome?
Currently the types for "wxt/browser" are exported from webextension-polyfill.

[aklinker1]

@aiktb If you installed @types/chrome, you should be able to access these types through the chrome global.

function registerCommand(command: chrome.commands.Command) {
  // ...
}

Because of the way the @types/chrome is written with namespaces, I can't really rename chrome to browser... But I'd prefer to export these types without using the word "chrome".

[Timeraa]

browser

Will test it out in my extension in a few and report back issues if I encounter them

[Timeraa]

Tested and works just fine!

[1natsu172]

Tested and works me too. If there's anything that have an impact at runtime, let me know, and I'll test it.

[typed-sigterm]

tested, works fine too :)

[AsakuraMizu]

What about aliasing webextension-polyfill to some wrapper (maybe a virtual entrypoint)? For example, I want to use webext-core packages, but they have dependencies on webextension-polyfill.

[aklinker1]

What about aliasing webextension-polyfill to some wrapper (maybe a virtual entrypoint)? For example, I want to use webext-core packages, but they have dependencies on webextension-polyfill.

So there's two approaches:

1. Just remove webextension-polyfill from WXT so it's not included in your extension when importing wxt/browser
2. Setup an alias to completely remove the polyfill from ALL dependencies and sub-dependencies, like webext-core

extensionApi implements the first approach. That way if a dependency depends on the polyfill, it doesn't break the dependency.

If you want to fully remove the polyfill from all dependencies, you can setup the alias yourself:

// wxt.config.ts
export default defineConfig({
  vite: () => ({
    alias: {
      'webextension-polyfill': path.resolve('polyfill-replacement.ts'),
    },
    ssr: {
      noExternal: ['@webext-core/storage']
    },
  }),
});

You need to add all dependencies that rely on webextension-polyfill to the ssr.noExternal option so that Vite knows to process those modules and have the alias take effect.

// polyfill-replacement.ts
import { browser } from 'wxt/browser/chrome';

export default browser;

But be aware this can break any dependencies that rely on polyfill-specific behaviors. This WAS the behavior with the old experimental option before this one, but I changed it to just remove the polyfill from WXT to avoid breaking other dependencies.

[joealden]

@aklinker1 think I've found a bug with type generation using this feature:

browser.runtime.getURL isn't available at all - not really sure why as I'd think path.d.ts would correctly override the value in index.d.ts, which chrome.d.ts would then use? Maybe the fact that we are importing WxtRuntime changes TypeScript's behaviour?

FYI I'm on the latest TS version as of now (5.6.2).

[aklinker1]

@joealden I also had a similar issue in one of my work repos. The problem was that I wasn't extending the .wxt/tsconfig.json.

So make sure either it's extended in your tsconfig:

{
  "extends": "./.wxt/tsconfig.json"
}

or make sure to include .wxt/wxt.d.ts somewhere else in your typescript project:

/// <reference types="./.wxt/wxt.d.ts" />

[joealden]

@aklinker1 thanks! Is that documented (as I presume it'd not specific to wxt/browser/chrome but wxt/browser too and any other type-gen APIs)? As I followed https://wxt.dev/get-started/installation.html#from-scratch and don't see a mention of this (or in https://wxt.dev/guide/key-concepts/web-extension-polyfill.html)?

[aklinker1]

I have it documented in a big rewrite I'm doing: https://github.com/wxt-dev/wxt/blob/docs-structure-update/docs/guide/config/typescript.md

Will add the part about the declaration file though.