Don't use webextension-polyfill by default

[aklinker1]

Feature Request

Currently, WXT's browser is the default export from webextension-polyfill. However, now that Chrome doesn't support MV2 extensions, and Firefox has MV3 support, it's not really doing anything anymore... It's main features were:

1. Add promise-based API to chrome's MV2 implementation
2. Providing a single global variable so you don't have to use both chrome and browser

However, those two features are no longer necessary:

1. Add promise-based API to chrome's MV2 implementation
   • Firefox and other browsers all support MV3 now, and Firefox's MV2 APIs are already promise-based. So you can write promise-based API calls and it will work on all browsers
2. Providing a single global variable so you don't have to use both chrome and browser
   • All browsers now support the chrome global, but WXT will continue to re-export it's own browser variable.

So how is WXT going to remove the polyfill?

First, it will provide some flag in config to continue using it if you want, but the polyfilll will not be the default. It will be moved to an optional peer-dependency so it's not even installed if it doesn't have to be.

Second, we'll be replacing @types/webextension-polyfill with @types/chrome. This will address lots of the problems with missing API and manifest types, at the cost of not being able to use type errors to know what's supported by all browsers and what's not. Either way, both ways have problems, but I think @types/chrome will provide a better DX.

Finally, we'll need to update wxt/testing to make sure it properly fakes the API. Not sure if @webext-core/fake-browser is still the best option for providing a fake version during development. Edit: Been looking and can't find anything else on NPM

So in summary, you shouldn't have to make any changes to your source code or tests. That's the goal, to make this transition as seemless as possible. You'll be able to opt into using the polyfill from wxt.config.ts. There will be breaking changes to types, don't think I can get around that.

If you use a library that includes the polyfill, it will work just fine, the polyfill will still be included.

Is your feature request related to a bug?

#506 - The vite-node solution works well, but the polyfill is getting in the way.

#521 - Improve manifest typing

#299 - Improve runtime API typing

What are the alternatives?

N/A

Additional context

• Discord: https://discord.com/channels/1212416027611365476/1253736416425410560

[aiktb]

Does the default build target for wxt build -b firefox change to MV3?

[aklinker1]

Does the default build target for wxt build -b firefox change to MV3?

Good call out... I'm going to say no for now. MV2 for Firefox is a better user experience and there are no problems with dev mode (MV3 CSP blocks loading scripts from localhost). So I'm a little hesitant to switch the default.

Also, I don't believe Firefox MV3 is a blocker for this specific issue. The polyfill isn't doing anything to Firefox now that promises are supported by all browsers by default. MV2 or MV3, for Firefox, doesn't matter.

Do you want to switch to MV3 by default? If so, what are your reasons @aiktb? Maybe we continue this conversation on #230

[aiktb]

mozilla/webextension-polyfill#210

webextension-polyfill causes shorter stack traces, I've tripped over this issue several times and recently ran into it again.
It makes debugging the extension more difficult.
In this case, the location of the reported error may even change:
In content-script:

In background:

[aiktb]

chrome.tabs.query is not compatible with firefox ...
I'm afraid that using the chrome namespace alone won't support firefox for this reason.

popup.html:

[aklinker1]

Perfect, thanks for sharing! I'm planning on manually polyfill-ing things like this so it just works. If you notice anything else, please share!

[aiktb]

chrome.tabs.query is not compatible with firefox ... I'm afraid that using the chrome namespace alone won't support firefox for this reason.

popup.html:

The essence of the problem I found is that the API under the chrome namespace in Firefox MV2 is based on callbacks, it's not an alias for browser.

[aklinker1]

Alright, I've done some refactoring and added an option to preview what the API will look like. It is available in v0.19.0!

1. Enable the option

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

2. Install @types/chrome and prepare the project

   pnpm i -D @types/chrome
   pnpm wxt prepare

To make sure the polyfill has been removed, do a build analysis:

pnpm build --analyze --analyze-open

Note

If dependencies import webextension-polyfill, like @webext-core/storage, the polyfill will be in your bundle, but WXT and any code you write will not be using the polyfill. This just means your code will work and the NPM package will work. If you want to fully remove the polyfill, don't use packages that depend on it, or open a PR for that package to remove it.

There should be no other code changes required. Your extension should work the same way as before. If you run into issues, either at runtime or with types, please report them!

[aklinker1]

I will also add, as of 0.19.0, the manifest type in your wxt.config.ts will still be using the type from the polyfill. Once the polyfill is no longer the default, the type will be updated.

[aklinker1]

Closing this issue in favor of #868