Building a cross-browser extension

The introduction of the browser extensions API created a more 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
  • 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 recommended because, in addition to being the proposed standard, it 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 have been adopted as part of the proposed standard, as they greatly simplify asynchronous event handling, particularly where you need to chain events together.

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.

So, how do you take advantage of promises easily, when Firefox is the only browser supporting them? 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.

You install the WebExtension browser API Polyfill into your development environment using npm or download it directly from GitHub releases. You then reference browser-polyfill.js in:

  • manifest.json, to make 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": [
     "browser-polyfill.js",
     "background.js"
   ]
 }
}

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

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:

  • Lack of support for an entire function. For example, at the time of writing, Edge didn’t provide support for the privacy function.
  • 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.
  • 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.

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.

The approach you should take, where there are differences among the APIs, is to offer either alternative implementations or fallback functionality. Remembering that 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 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 main four browsers fall broadly into three categories:

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

Publishing

Each of the four major browsers maintain browser extension stores, and as a consequence you need to approach adding and updating your extension in each separately. In some cases you can upload your extension using a utility. Each of the stores also performs a review of your extension to check for security vulnerabilities. The table below summarizes the approach and features of each store:

 

Registration fee

Upload utility

Pre-publication review process

Account two factor authentication

Firefox

No

web-ext

Automatic, a few seconds1

No

Chrome

Yes

Yes

Automatic, less than an hour

Yes

Opera

No

No

Manual, no SLA provided

No

Edge

Yes

No

Manual, up to 72 hours2

Yes

1) 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.

2) At the time of writing, Microsoft was only allowing publication of preapproved extensions.

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 that 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

Conclusion

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 theAPI 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 extinction packaging and the processes for submitting to each of the extension stores.

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.

Document Tags and Contributors

Contributors to this page: rebloor
Last updated by: rebloor,