WebExtensions in Firefox 55

Firefox 55 landed in Beta this week, so it’s time for another update on WebExtensions. Because the development period for this latest release was about twice as long as normal, we have many more updates. Documentation for the APIs discussed here can be found on MDN.


The webRequest API has seen many improvements. Empty types and URLs in webRequest filters are now rejected. Requests can be cancelled before cookie processing occurs. Websockets can be processed through webRequest using the ws:// and wss:// protocols. Requests from the top frame now have the correct frameId, and more error conditions on requests are picked up by the onErrorOccurred event.

The sidebar API now re-opens automatically if you reload the add-on using about:debugging or web-ext. If you are following along with project Photon, you’ll note that the sidebar works great with the new Photon designs. Shiny!

The runtime.onMessageExternal API has been implemented, which allows WebExtensions add-ons to communicate with other WebExtensions add-ons. The runtime.onInstalled API will now activate if an add-on is installed temporarily, and the event will now include the previousVersion of the extension.

In order to limit the amount of CSS that a developer has to write and provide some degree of uniformity, there is a browser_style option for the browserAction API. We’ve also provided this to options V2 and the sidebar APIs.

Context menus now work in browserAction popups. The onClickData event in the context menu also gets the frameID. Context menu clicks can now open browser actions, page actions and sidebars. To do this, specify _execute_browser_action, _execute_page_action or _execute_sidebar_action in the command field for creating a context menu.

If you load a page from your extension, you get a long moz-extension://…. URL in the URL bar. We’ve added a notification in the identity box to indicate that the page what extension loaded it.

Other changes include:

A new API is now available for the nsiProfiler. This allows the Gecko Profiler to be used without legacy add-on support. This was essential for the Quantum Flow work happening in Firefox. Because of the sensitive nature of the content and the limited appeal of this API, access to this API is currently restricted.


With Firefox 55, the user interface for required and optional permissions is now enabled for WebExtensions add-ons. Required permissions and hosts will trigger a prompt on installation for the user. Here’s an example:

When an extension is updated and the hosts or permissions have changed, the current extension remains enabled, but the user has to accept the updated permissions in order to continue.

There is also a new user interface for side loading add-ons that is more consistent with other installation methods. Side loading is when extensions are installed outside of Firefox, by other software. It now appears in the hamburger menu as a notification:

This permissions dialog is slightly different as well:

Once an extension has been installed, if it would like more permissions or hosts, it can ask for those as needed — these are called optional permissions. They are accessible using the browser.permissions.request API. An example of using optional permissions is available in the example repository on github.

Developer tools

With the introduction of devtools.inspectedWindow.eval bindings, many more add-ons are now able to support WebExtensions APIs. The developer tools team at Mozilla has been reaching out to developers with add-ons that might be affected as you can see on Twitter. For example, the Redux DevTools extension is now a WebExtensions add-on using the same code base as other browsers.

An API for devtools.panels.themeName has been implemented. The devtools panel icon is no longer inverted if a light theme is chosen.

There have been some improvements to the about:debugging page:

These changes are aimed at improving the ease of development. Temporary extensions now appear at the top of the page, a remove button is present, help is shown if the extension has a temporary ID, the location of the extension on the file system is shown, and the internal UUID is shown.


Firefox for Android has gained browserAction support. Currently a textual menu item is added to the bottom of the menu on Android. It supports browserAction.onClicked and setTitle and getTitle. Tabs support was added to pageAction.


The beginnings of theme support, as detailed in this blog post, has landed in Firefox. In Firefox 55 you can use the browser.theme.update API. The theme API allows you to set some key values in Firefox such as:

 images: {
   headerURL: "header.png",
 colors: {
   accentcolor: "#000",
   textcolor: "#fff",

This WebExtensions API will apply the theme to Firefox by setting the header image and some CSS colors. At this point the theme API applies a very similar set of functionality as the existing lightweight theme. However, using this API you can do this dynamically in your extension.

Additionally, browser.management APIs have been implemented for themes. These allow you to enable and disable themes by only using the management API. For an example check out the example repository on github.


The proxy API allows extension authors to insert proxy configuration files into Firefox. This API implementation is quite different from the one in Chrome to take advantage of some of the improved support in Firefox for proxies. As a result, to prevent confusion, this API is not present in the chrome namespace.

The proxy configuration file will contain a function for dealing with the incoming request:

function FindProxyForURL(url, host) {
 // ...

And this will then be registered in the API:


For an example of using the proxy API, please see the repository on github.


One focus of the Firefox 55 release was the performance of WebExtensions, particularly the scenario where there is at least one WebExtension on startup.

These performance improvements include speeding up host matching, limiting the cloning of add-on messages, lazily loading APIs when they are needed. We’ve also been adding in some telemetry measurements into Firefox, such as background page load times and extension start up times.

The next largest performance gain is the moving of WebExtensions add-ons to their own process. To enable this, we made the debugging tools work seamlessly with out-of-process add-ons. We are hoping to enable this feature for Windows users in Firefox 56 once the remaining graphics issues have been resolved.

You can see some of the results of performance improvements in the Quantum newsletter which Ehsan posts to his blog. These improvements aren’t just limited to WebExtensions add-ons. For example, the introduction of off script decoding brought a large performance improvement to startup measurements for all Firefox users, as well as those with WebExtensions add-ons:


As ever we need to thank the community who contributed to this release. This includes: Tushar Saini, Tomislav Jovanovic, Rob Wu, Martin Giger and Geoff Lankow. Thank you to you all.

20 responses

  1. jxn wrote on :

    Great improvements! Is there an outline of what WebExtension functionality will or will not be planned for Android? As Extension Doomsday approaches, it’d be nice to know what webextensions would at least be portable when the api’s are available.

    Also, will Mozilla/Pocket be porting Pocket extension to firefox before the FF 57 release?

    1. Andy McKay wrote on :

      Please see https://wiki.mozilla.org/WebExtensions/RoadMapFirefox57#Android. I don’t know about the Pocket extension, maybe best to ask them directly. There is also this bug: https://bugzilla.mozilla.org/show_bug.cgi?id=1282905

  2. Stefan wrote on :

    Hi there,

    Is there any documentation about browser.theme or and sample file?
    Because in Firefox Nightly v56.0a1 it show me just this error:
    browser.theme is undefined

    I want to add this in the Turn Off the Lights Firefox extension. One click, and it dims everything 🙂


    1. Andy McKay wrote on :

      Ensure you have the theme permission. Here’s an example: https://github.com/mdn/webextensions-examples/pull/230, I didn’t list it because it hasn’t been merged yet.

      1. Stefan wrote on :

        Thank you.

  3. Ron wrote on :

    When trying to use the proxy API I get the error:
    “TypeError: browser.proxy is undefined”

    The line with which the error is associated is:

    I used the example from the repository on github

    Anybody an idea,?

    1. Andy McKay wrote on :

      Have you added the proxy permission to your manifest, for example: https://github.com/mdn/webextensions-examples/blob/master/proxy-blocker/manifest.json#L30

      Support via blog comments isn’t the most effective method, I would suggest one of our other methods instead: https://wiki.mozilla.org/Add-ons#Getting_in_touch

  4. Stefan wrote on :

    A new question about this “theme”, will this support also the “optional_permissions”?
    Here it said an error on my Firefox Nightly

    1. Andy McKay wrote on :

      I don’t know if that’s been added or not. Support via blog comments isn’t the most effective method, I would suggest one of our other methods instead: https://wiki.mozilla.org/Add-ons#Getting_in_touch

  5. Alexander wrote on :

    I’ve tried several extensions build with new API. This is a disaster. Mouse gestures do not work with new empty tabs and about: pages, new tree style tabs are unusable, some extensions are simply impossible to implement.

    Extensions was only reason why I use Firefox! I don’t know what to do now, it is frightening and heartbreaking. You are KILLING your browser

  6. ANON wrote on :

    That permissions prompt for external install is very wordy.

  7. Edouard Balladur wrote on :

    What I’m interested about is whether there are enough features for a port or remake of Nuke Anything (currently Nuke Anything Enhanced).

    This is a very good and long-running extension : right-click on an overlay picture, a ribbon that prevents you from reading the article comfortably etc. and select “remove” to get rid of them. (with a complex ribbon/toolbar you might have to do it a few times)

    It might be a bit complex but it seems to deal with the web page content only. So I’d think it would be a good candidate for something to run as a WebExtension, but I don’t know if some small glue is missing between the GUI realm and the web realm, I have no idea.

    I don’t know who was the original author of the extension, if it did change hands or was forked. I want to thank the current (or last) maintainer at the least.
    I think it’s one of those small piece of software whose every user likes.

  8. Noitidart wrote on :

    Very cool. I like that side loading interface. Is there some docs on how to side load to get this affect?

    1. Andy McKay wrote on :

      See: https://developer.mozilla.org/en-US/Add-ons/Installing_extensions and https://developer.mozilla.org/en-US/Add-ons/Adding_extensions_using_the_Windows_registry

      1. Noitidart wrote on :

        Thanks Andy!

  9. Dark_Ronius wrote on :

    Worst. Update. Ever.

    I have had Nightly updates which are more stable than this. Ever since 55 has gone live, I have had a stream of crashes which I haven’t been able to pin down. Of the 11 extensions I had installed, 8 are now labelled “legacy”- worrying as it includes uBlock and https everywhere, as well as Blur which I also use. Even AdBlock is classed as “legacy”.

    In all my time as a Firefox user, I have never been this appalled with rollout. For more than 10 years, the Firefox Beta Builds have been better than what other projects would class as their “stable” build. This had always given me confidence in recommending the stable version to family and friends. I have also regularly alternated between Beta/Developer/Nightly (after a clean install) depending on how desperate I have been to test the latest features.

    Now, I had stayed on beta the last 6 months mostly due to the WebExtension changes that I have already complained about previously on this blog. I allowed the beta to update, however, out of an optimism that maybe I’d put up with it and eventually get over it. This was your chance to woo me over and convince me I’d get over it.

    The result? Well, it was immediately obvious as the contents of the context boxes Blur creates is replaced by text telling me Firefox doesn’t know how to handle thje links anymore. Then, to go and disable it for the time being, to my horror I find almost the entire list of add-ons are classed as “legacy”. Then, almost on cue, the “unhandled exception” crashes started. And continued even after disabling all add-ons classed as legacy. Only Safe mode worked, which suggested to me it could be Flash. But seriously?

    I know I’m going to get the inevitable marketing dribble of how and why changes have been made, but seriously. How could this be screwed up so badly? NEVER, in all my time with the apparently “dreaded” xul/old add on system (that had worked for 10 years mind), has an update caused me such a headache for me. And, on top of this, is the sinking feeling of seeing most of my browser functionality considered “legacy”. I currently need a back-up browser for when Firefox has a moment. The irony- Firefox was originally the browser I moved to because internet explorer was so unstable!!

    I’m willing to make a bug report or whatever, but that’s the limit I’m willing to go. Wheras before I would have gone out of my way to cull old or crap extensions, or been happy to do a clean install and automatically assume all guilt for making a change that has caused this. Now, the ball is in your park considering all the under the hood changes. I’m not willing to spend the huge amount of time to fix or search for solutions as I might have done in the past, as this experience has utterly eroded the last of the brand loyalty I have. Every time I use Vivaldi, it is convincing me more and more just to go with that. Maybe have Pale Moon as a backup. I’m sure yoiu’re sick of messages like this; but how else am I to express my shear frustration? For a non-profit I have invested so much time and energy promoting, donating to, etc? Indeed, the last browser non-profit? Again, this was the one chance to convince me the future is better like this. The only way I can see that is with another browser.

  10. Dimitre wrote on :

    I want to port my addons to webextensions but there is an issue very important to address first

    And it seems in bugzilla the priority is none.
    And it is very important to address that before legacy addons are phased out

    Thank you

  11. Mikael Sampson wrote on :

    I’m sad to discover that the toolbar for addons disappear. FF was the last browser that had this and now it’s 10 times more troublesome to use login-toolbars that helps in my business. I would rather have a slower browser, than have to go through several steps each time I need to login to some site. I never though the world would go backwards by removing tools that made the world far easier.

  12. Upset User wrote on :

    I moved to Developer so I could continue to use the “unverified” Permit Cookies add-on. Today I was updated to 55.0b3, and now all eight of my add-ons are shown as “legacy.”

    Unacceptable. I’m not a developer, don’t understand or care about all the technical jargon in this blog. All I know is, my Firefox is broken and my ability to customize it as I wish has been eliminated.

    Goodbye, Firefox.

  13. Ray wrote on :

    I had to rollback to 52 as all my extensions became legacy and unusable. They are there to improve my browsing, so I’m not willing to sacrifice them for the current “upgrade”.