Tell your users what to expect in your WebExtensions version

The migration to WebExtensions APIs is picking up steam, with thousands of compatible add-ons now available on (AMO). To ensure a good experience for the growing number of users whose legacy add-ons have been updated to WebExtensions versions, we’re encouraging developers to adopt the following best practices.

(If your new version has the same features and settings as your legacy version, your users should get a seamless transition once you update your listing, and you can safely ignore the rest of this post.)

If your new version has different features, is missing legacy features, or requires additional steps to recover custom settings, please do one or both of the following.

Update your AMO listing description

If your new version did not migrate with all of its legacy features intact, or has different features, please let your users know in the “About this Add-on” section of your listing.

If your add-on is losing some of its legacy features, let your users know if it’s because they aren’t possible with the WebExtensions API, or if you are waiting on bug fixes or new APIs to land before you can provide them. Include links to those bugs, and feel free to send people to the forum to ask about the status of bug fixes and new APIs.

Retaining your users’ settings after upgrade makes for a much better experience, and there’s still time to do it using Embedded WebExtensions. But if this is not possible for you and there is a way to recover them after upgrade, please include instructions on how to do that, and refer to them in the Version notes. Otherwise, let your users know which settings and preferences cannot be recovered.

Add an announcement with your update

If your new version is vastly different from your legacy version, consider showing a new tab to your users when they first get the update. It can be the same information you provide in your listing, but it will be more noticeable if your users don’t have to go to your listing page to see it. Be sure to show it only on the first update so it doesn’t annoy your users.

To do this, you can use the runtime.onInstalled API which can tell you when an update or install occurs:

function update(details) {

if (details.reason === 'install' || details.reason === 'update') {

browser.tabs.create({url: 'update-notes.html'});




This will open the page update-notes.html in the extension when the install occurs. For example:

For greater control, the runtime.onInstalled event also lets you know when the user updated and what their previous version was so you can tailor your release notes.

Thank you

A big thanks to all the developers who have put in the effort to migrate to the WebExtensions API. We are here to support you, so please reach out if you need help.

7 comments on “Tell your users what to expect in your WebExtensions version”

  1. .w wrote on

    Displaying onUpdate page is one of the most annoying things ever happened… :/

  2. xxxfreetubes wrote on

    Displaying on Update page is one of the most annoying things…..

    well well what to doo…

  3. oasaccounting wrote on

    Thank you for the post

  4. Harry Ong wrote on

    There will be no WebExtensions version for addons I use coz the new framework basically killed it. Thank you, Mozilla.

    1. Amy Tsay wrote on

      Hi Harry, would you mind me asking what extensions you’re using?

      1. Nina So wrote on

        Sorry to hijack this thread but why do even need to ask? Look at your Top 20 extensions and see which extensions won’t be getting a WebExtensions version. For example, the very useful and unique DownThemAll won’t be getting one simply because you enforce WebExtensions in the form that doesn’t cover the needs all of your most used extensions. Please rethink this decision. It’s not too late yet. Else, Firefox will bleed even more users than it will possibly gain.

  5. Elias Rodriguez wrote on

    The developers of my favorite extensions told me not to expect a WebExtensions version because it is simply not possible to develop one given how crippled the new framework is. *thumbs down*

    Thank you, Mozilla. I might as well switch to Google Chrome if you intend to push down those weak Google Chrome extensions down my throat.