MDN’s new design is in Beta! A sneak peek:

Porting a legacy Firefox add-on

If you have developed a Firefox add-on using XUL/XPCOM or the Add-on SDK, this page will help you migrate your add-on to the WebExtension format. WebExtensions are now the standard for add-on development in Firefox. It will be the only type of add-on supported in Firefox by the end of 2017 with the release of Firefox 57.

Quick start

  1. Get an idea of the main things you'll have to change in your add-on:
  2. Rewrite your add-on code. See below for migration paths for different types of add-ons. From Firefox 51 onwards, you can embed a WebExtension in a bootstrapped extension or an SDK add-on, and can thus port a legacy add-on a piece at a time, and have a working add-on at each step. See Embedded WebExtensions.
  3. When you're ready to submit the WebExtension version of your add-on to AMO... wait a minute... are you truly ready? Because of the add-ons permissions model, you cannot revert from a WebExtension back to a legacy add-on 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 add-on container, which allows you to test your WebExtension migration but still go back if needed in an emergency.
  4. When you're really ready to submit the WebExtension version of your add-on to AMO, first port your old add-on ID to the new WebExtension manifest.json file. Your add-on 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 applications section of the WebExtension manifest.json file. Then you can submit your add-on update to AMO as your normally would.

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

Migration paths

SDK Add-ons

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


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

Partial migration

Embedded WebExtensions - You can now embed a WebExtensions add-on inside an existing SDK or bootstrapped add-on. This is especially useful to developers of SDK or bootstrapped add-ons who want to start migrating to WebExtensions and take advantage of new APIs like Native Messaging, but can’t fully migrate yet. It’s also useful for developers who want to complete data migration towards WebExtensions, and who want to take parts of their add-on that are not compatible with multiprocess Firefox and make them compatible.

Not all add-ons will be able to migrate to WebExtensions without having to drop any features. But we want to work with you to get as many add-ons migrated as possible with the functionality you created intact. We invite you to contribute to its evolution, and we look forward to working with you.

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 WebExtensions API, please file a bug. These will be triaged and processed in a bi-weekly public meeting.


  • web-ext is a command line tool designed to speed up various parts of the WebExtension development process, making development faster and easier.
  • Lookup tool to check your add-on type and get porting resource recommendations
  • WebExtensions Helper speeds up browser add-on 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


Document Tags and Contributors

 Contributors to this page: Dietrich, wbamberg, bunnybooboo, cricciuto, Croydon
 Last updated by: Dietrich,