New Feature Announcement: Introduction of 'browser' Namespace for Chromium Extension APIs

[Justin Lulejian]

Dear Chromium Extension Developers,

We are excited to announce a new feature that will provide you with more flexibility when developing Chromium extensions. Starting with the M136 release (stable release date of April 29th), we will introduce the browser namespace as an optional alternative to the existing chrome namespace for calling Chromium extension APIs. You can try this today using the --enable-features=ExtensionBrowserNamespaceAlternative flag in Chrome Canary. This change will be enabled by default in Chrome Canary the same or next day after this change is submitted (check the commits page to find the exact version).

Here are the key details of this update:

• Availability: The browser namespace will be available for all MV3+ extensions wherever extension developers can call Chromium extension APIs, including content scripts, background contexts, and offscreen documents.

• Equivalence: The chrome and browser namespaces refer to the exact same extension API objects. For example, chrome.<api> is equivalent to browser.<api> (e.g chrome.<api> === browser.api). They can be used interchangeably.

• Object Difference: While the APIs are the same, chrome and browser are different objects. Setting browser.my_custom_var does not automatically set chrome.my_custom_var (and vice versa).

• Existing Extensions: We understand that some extensions may be using the non-existence of the browser namespace to detect when they are not running in Chromium. If so, we’d like to know why you are doing this as there may be better options available. In the meantime, a workaround would be to call /Chrom(ium|e)/.test(navigator.userAgent) to detect Chromium or branded Chrome.

• Community Feedback: We are aware that this change might affect some existing extensions. We are relying on community reports to determine if this causes significant disruption and we need to make changes to the rollout plan. We hope that the almost 6 week lead time before stable release will provide sufficient time for those extensions to update their behavior.

We hope that this change will make it easier to develop extensions across multiple browsers.

If you have any questions, please feel free to reach out to us.

Thank you,
Justin, on behalf of the Chromium Extensions Team

[Juraj M.]

Whoa, nice! 🎉

This is the best extensions related news of this year! (maybe right after the ability to cancel the release/review :D)

Quick question, extensions that are using webextension-polyfill should be unaffected, right?

Actually... maybe not?

You see, there is ONE MORE bug you should 100% fix before you release this. And it's something that the webextension-polyfill is still handling:
https://issues.chromium.org/issues/40753031

(and it cures spaghetti code!)

[woxxom]

> using the non-existence of the browser namespace to detect when they are not running in Chromium.

I check for `runtime` like self.browser?.runtime

>  webextension-polyfill should be unaffected, right?

Right. They check for runtime.id: link.

[woxxom]

> there is ONE MORE bug you should 100% fix before you release this

Indeed. Otherwise Chrome will break all extensions that rely on the fact that if `browser` is present then it supports Promise in onMessage listener.

[Justin Lulejian]

Juraj/Woxxom: Thank you for pointing this out and I can see how the above change will break that for some extensions. I've temporarily disabled the feature by default while we look into how to approach this. I'll update this thread once we figure out our next steps.

In the meantime, if anyone wants to try the feature the `--enable-features=ExtensionBrowserNamespaceAlternative` command line flag will continue to work in turning this on in Chrom(ium)e Canary (and other channels as it progresses through the release system).

[Juraj M.]

Just to confirm, my extensions are indeed broken in Canary with the flag enabled.

As mentioned in the issue (https://issues.chromium.org/issues/40753031), the "return Promise to reply" behavior could be enabled only for the "browser" namespace.
That way, existing extensions that uses "chrome" namespace wouldn't be affected even if they return a Promise (e.g. if they use "async function" handler).