Submit or Manage Extensions

Porting a legacy Firefox extension

If you have developed a Firefox extension using XUL/XPCOM or the Add-on SDK, this page will help you migrate your extension to use WebExtensions APIs. The standard to build extensions for Firefox is to use WebExtensions APIs. It will be the only type of extension supported in Firefox by the end of November 2017 with the release of Firefox 57.

Support for extensions using XUL/XPCOM or the Add-on SDK was removed in Firefox 57, released November 2017. As there is no supported version of Firefox enabling these technologies, this page will be removed by December 2020.

Quick start

  1. Get an idea of the main things you'll have to change in your extension:
  1. Rewrite your extension code. See below for migration paths for different types of extensions. From Firefox 51 onwards, you can embed an extension built using WebExtension APIs in a bootstrapped extension or an SDK add-on, and can thus port a legacy extension a piece at a time, and have a working extension at each step. See Embedded WebExtensions for more information.
  2. When you're ready to submit the WebExtension version of your extension to AMO... wait a minute... are you truly ready? Because of the extensions permissions model, you cannot revert from WebExtensions back to using a legacy extension format. So test thoroughly, because this is a permanent one-way trip. Also, see the hybrid example below. If you're not ready, you can embed your WebExtension in a legacy extension container, which allows you to test your extension migration but still go back if needed in an emergency.
  3. When you're really ready to submit the WebExtension version of your extension to AMO, first port your old add-on ID to the new WebExtension manifest.json file. Your extension must have the same ID as previous versions. Copy the value in the "id" field from your package.json file into the id field in the browser_specific_settings section of the WebExtension manifest.json file. Then you can submit your extension update to AMO as your normally would.

Note that this is a one-way conversion: You cannot update an extension using WebExtensions to use a legacy technology. This means that you must be sure that you are ready to commit to using WebExtension APIs before you submit the updated add-on to AMO.

Migration paths

SDK Extensions

Here is the comparison chart showing SDK APIs and their WebExtensions format counterparts. If you don't see the APIs you need to port to use WebExtensions APIs, look below to learn how to request APIs and also how to implement them.

XUL/XPCOM Extensions

Here is the comparison chart showing XUL/XPCOM APIs and their WebExtensions format counterparts. If you don't see the APIs you need to port to use WebExtension APIs, look below to learn how to request APIs and also how to implement them.

Don't see the WebExtensions APIs you need?

Develop WebExtension APIs for Firefox - If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of approved APIs that you can start contributing to.

Experiment with new WebExtension APIs - If you want to prototype and tinker with WebExtensions APIs without having to build Firefox, WebExtensions Experiments is for you!

Request a new WebExtensions API - If you want to request a new WebExtensions API, please read this page.

Tools

  • web-ext is a command line tool designed to speed up various parts of the extension development process, making development faster and easier.
  • WebExtensions Helper speeds up browser extension development by providing utilities for WebExtensions-based (Firefox, Chrome, Opera and Edge) extensions
  • Chrome Extension generator creates everything you need to get started with extension development. You can choose Browser UI (Browser,Page Action, Omnibox) type and select permissions you need.
  • Extensionizr is a wizard that helps you create a basic extension
  • Chrome Boilerplate is boilerplate code for Chrome WebExtension.
  • Skeleton Chrome Extension is an extension bootstrap and template

Contact

You can use the links here to get help, keep up to date with news around add-ons, and give us feedback.