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.
- Get an idea of the main things you'll have to change in your add-on:
- Familiarize yourself with the WebExtension format and structure, and build a basic example.
- If your add-on is based on XUL and XPCOM, whether it's an overlay extension or a bootstrapped extension, see Comparison with XUL/XPCOM extensions to find out which Web Extension APIs correspond with the legacy APIs you're using.
- If your add-on is based on the Add-on SDK, see Comparison with the Add-on SDK to find out which Web Extension APIs correspond with the legacy SDK APIs you're using.
- 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.
- 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.
- 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.
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.
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!
- 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
- WebExtensions Project Page on the Mozilla Wiki
- How-to guides covering common add-on developer cases, like intercepting web requests and adding a button to the toolbar
- Comparison with the Add-on SDK
- Comparison with XUL/XPCOM extensions
- Browser compatibility table for all WebExtensions APIs
- Examples of WebExtensions