Building a cross-browser extension

The introduction of the browser extensions API created a uniform landscape for the development of browser extensions. However, among the browsers that use the extensions API (the major ones being Chrome, Firefox, Opera, and Edge), there are differences in both the implementation of the API and the scope of coverage. And then, Safari uses its own proprietary Safari Extensions JS.

Maximizing the reach of your browser extension means developing it for at least two different browsers, possibly more. This article looks at six of the main challenges faced when creating a cross-browser extension, and in each case suggests how to address the challenge.

This article doesn’t discuss creating browser extensions for Safari. It may be possible to share some resources with a Safari extension, such as images and HTML content. However, the JavaScript coding needs to be undertaken as a separate development project, unless you wish to create your own polyfill.

Cross-platform extension coding hurdles

There are six areas you need to address when tackling a cross-platform extension:

  • API namespace
  • API asynchronous event handling
  • API function coverage
  • Manifest keys
  • Extension packaging
  • Extension Publishing

API namespace

There are two API namespaces in use among the four main browsers:

  • browser.*, the proposed standard for the extensions API, used by Firefox and Edge.
  • chrome.* used by Chrome and Opera.

Firefox also supports the chrome.* namespace for APIs that are compatible with Chrome, primarily to assist with porting. However, using the browser.* namespace is preferred.  In addition to being the proposed standard, browser.* uses promises—a modern and convenient mechanism for handling asynchronous events.

Only in the most trivial extensions is namespace likely to be the only cross-platform issue that has to be addressed. It’s therefore rarely, if ever, helpful to attempt to address this issue alone. The best approach is to address this with asynchronous event handling.

API asynchronous event handling

There are two approaches to handling asynchronous events in use among the four main browsers:

  • Promises, the proposed standard for the extensions API, used by Firefox.
  • Callbacks, used by Chrome, Edge, and Opera.

Firefox also supports callbacks for the APIs that support the chrome.* namespace. However, using promises (and the browser.* namespace) is recommended. Promises has been adopted as part of the proposed standard. It greatly simplifies asynchronous event handling, particularly where you need to chain events together.

Note: If you’re unfamiliar with the differences between these two methods, take a look at Getting to know asynchronous JavaScript: Callbacks, Promises and Async/Await or the MDN Using promises page.

The WebExtension browser API Polyfill

So, how do you take advantage of promises easily, when Firefox is the only browser supporting it? The solution is to code for Firefox using promises and use the WebExtension browser API Polyfill!

This polyfill addresses the API namespace and asynchronous event handling across Firefox, Chrome, and Opera. At the time of writing (November 2018), support for Edge was under development.

To use the polyfill, install into your development environment using npm or download it directly from GitHub releases.

Then, reference browser-polyfill.js in:

  • manifest.json, to make it available to background and content scripts.
  • HTML documents, such as browserAction popups or tab pages.
  • The executeScript call in dynamically-injected content scripts loaded by tabs.executeScript, where it hasn’t been loaded using a content_scripts declaration in manifest.json.

So, for example, this manifest.json code makes the polyfill available to your background scripts:

 // ...
 "background": {
   "scripts": [

Your goal is to ensure that the polyfill executes in your extension before any other script expecting the browser.* API namespace executes.

Note: For more details and information on how to use the polyfill with a module bundler, see the project’s readme on GitHub.

There are other polyfill options but, at the time of writing, none provide the coverage of the WebExtension browser API Polyfill. So, where you haven’t targeted Firefox as your first choice, your options are to accept the limitations of alternative polyfills, port to Firefox and add cross-browser support, or develop your own polyfill.

API function coverage

The differences in the API functions offered in each of the four main browsers fall into three broad categories:

  1. Lack of support for an entire function.
    For example, at the time of writing, Edge didn’t provide support for the privacy function.
  2. Variations in the support for features within a function.
    For example, at the time of writing, Firefox doesn’t support the notification function method onButtonClicked while Firefox is the only browser that supports onShown.
  3. Proprietary functions, supporting browser-specific features.
    For example, at the time of writing, containers was a Firefox-specific feature supported by the contextualIdentities function.

You can find details about the support for the extension APIs among the four main browsers and Firefox for Android on the Mozilla Developer Network Browser support for JavaScript APIs page. Browser compatibility information is also included with each function and its methods, types, and events in the Mozilla Developer Network JavaScript APIs reference pages.

Handling API differences

A simple approach to addressing these differences is to limit the functions used in your extension to functions that offer the same functionality across your range of targeted browsers. In practice, for most extensions, this approach is likely to be too restrictive.

Instead, where there are differences among the APIs, you should either offer alternative implementations or fallback functionality. (Remember: you may also need to do this to allow for differences in API support between versions of the same browser.)

The use of runtime checks on the availability of a function’s features is the recommended approach to implementing alternative or fallback functionality. The benefit of performing a runtime check is that if the function becomes available you don’t need to update and redistribute the extension to take advantage of it.

The following code enables you to perform a runtime check:

if (typeof <function> === "function") {
   // safe to use the function

Manifest keys

The differences in the manifest.json file keys supported by the four main browsers fall broadly into three categories:

  1. Extension information attributes.
    For example, at the time of writing, Firefox and Opera include the developer key for details about the developer, as well as the author, of the extension.
  2. Extension features.
    For example, at the time of writing, Edge did not support the commands key that enables shortcut keys to be defined for an extension.
  3. Key optionality.
    For example, at the time of writing, the author key is mandatory in Edge, but optional in the other main browsers.

Browser compatibility information is included with each key in the Mozilla Developer Network manifest.json key reference pages.

As manifest.json files tend to change little—except for release numbers, which may be different between the various browsers—creating and editing a static version for each browser is usually the simplest approach.

Extension packaging

Packaging an extension for distribution through the browser extension stores is relatively straightforward.

  • Firefox, Chrome, and Opera all use a simple zip format that requires the manifest.json file to be at the root of the zip package.  
  • However, submitting to the Microsoft store requires additional packaging of the extension file.

For details on packaging, refer to the guidance on the respective extension’s developer portals.

Extension publishing

Each of the four major browsers maintains browser extension stores. Each store also performs a review of your extension to check for security vulnerabilities. 

As a consequence, you need to approach adding and updating your extension for each store separately. In some cases, you can upload your extension using a utility.

The table below summarizes the approach and features of each store:

Browser Registration fee Upload utility Pre-publication review process Account two factor authentication




Automatic, a few seconds.

A manual review of the extension takes place after publication, which may result in the extension being suspended where issues that need fixing are found.





Automatic, less than an hour





Manual, no SLA provided





Manual, up to seven business days


Other considerations

Extension naming

Microsoft requires that extensions have unique names and provides a process for claiming one or more names for your extension through the Windows Dev Center. It may therefore be prudent to reserve an extension name with Microsoft, even if you’re not intending to support Edge immediately.

None of the other stores apply name restrictions.

Version numbering

The Firefox and Chrome stores require that each uploaded version has a separate version number. This means you cannot revert to an earlier version number if you come across issues in a release.

Share content

Even when you include developing extensions for Safari, there are a number of assets you can potentially share across all of your implementations. These include:

  • Images
  • HTML
  • CSS


When approaching a cross-platform extension development, addressing the fundamental differences between extension API implementations can be addressed by targeting Firefox and using the WebExtension browser API Polyfill. Following this approach you benefit from using API features that are closely aligned with the proposed extensions API standard and offer you the simplicity of promises for asynchronous event handling.

The bulk of your cross-platform work is likely to focus on handling variations among the API features supported by the main browsers. Creating your manifest.json files should be relatively straightforward and something you can do manually. You will then need to account for the variations in extension packaging and the processes for submitting to each of the extension stores.

You can use browser-extension-template to quickly set up a working project for building and publishing a browser extension.

Following the advice in this article, you should be able to create an extension that works well on all of the four main browsers, enabling you to deliver your extension features to more people.