[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.

[jalooc]

Fantastic upgrade strategy and the webextension-polyfill situation handling in general @aklinker1 🎖️

Reporting no issues in a simple project, will follow up once it grows ✔️

[aklinker1]

Seems like this is working well for people, I'm gonna enable extensionApi: "chrome" in new projects by updating the templates. This will get a few more people to test this out.

• chore: Enable extensionApi: chrome in template projects #1083

[dvlden]

I might have forgotten to give my input on this. Using it in latest release of my extension for Chrome and Firefox. Working flawlessly for ~60k users.

[1natsu172]

@aklinker1 We found a problem about the extensionApi . #1116

[aklinker1]

@aklinker1 We found a problem about the extensionApi . #1116

Huh, weird... @types/chrome is a direct dependency, so PNPM should be able to find it...

https://github.com/wxt-dev/wxt/blob/main/packages%2Fwxt%2Fpackage.json#L85

Quick fix, let's add the dependency to the templates for now.

[1natsu172]

Triple slash directives are removed at packages/wxt/dist/browser/chrome.d.ts to build. And pnpm will hoist @type/chrome. WXT can't find the path because didn't explicitly import it...…The theory is this, but not sure how to consider pnpm. 🤷

Agree to include it in the dependencies as a workaround for now.

[1natsu172]

@aklinker1 I submitted workaround PR. #1119

[mklueh]

@aklinker1

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

could you please elaborate on what is meant with "include somewhere else"? The <reference.../> XML from the docs is confusing, as ts configs are usually json.

So not sure if I understand it correctly, but I've put it into the root tsconfig.base.json as

"include": ["./.wxt/wxt.d.ts"]

Haven't had any issues so far, other than IntelliJ-related issues with linting, so I guess it's not totally wrong

[2wheeh]

@mklueh

could you please elaborate on what is meant with "include somewhere else"? The <reference.../> XML from the docs is confusing, as ts configs are usually json.

https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html

It means to include that directive somewhere at the global level.

[mklueh]

@mklueh

could you please elaborate on what is meant with "include somewhere else"? The <reference.../> XML from the docs is confusing, as ts configs are usually json.

https://www.typescriptlang.org/docs/handbook/triple-slash-directives.html

It means to include that directive somewhere at the global level.

Thanks.

To be honest using this feels totally wrong.

Is there any reason why it can't be added via tsconfig.includes in the extension's tsconfig.json?

{
  "extends": "../../../tsconfig.base.json",
  "includes": [
    ".wxt/wxt.d.ts"
  ]
}

Looks that it does what it should and its much cleaner than putting these references in files other than tsconfig

But maybe I'm missing the point here...

[aklinker1]

Yup, that works too. I only recommend references because that way you don't have to worry about merging your includes in the tsconfig file if it extends another TSConfig.