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 useWebExtensions 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.
- Get an idea of the main things you'll have to change in your extension:
- Familiarize yourself with the WebExtension format and structure, and build a basic example.
- If your extension 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 how WebExtensions can correspond with the legacy APIs you're using.
- If your extension is based on the Add-on SDK, see Comparison with the Add-on SDK to find out how WebExtensions can correspond with the legacy SDK APIs you're using.
- 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.
- 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.
- 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 applications 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.
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.
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.
- 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
- WebExtensions Project Page on the Mozilla Wiki
- How-to guides covering common extension 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 extensions
You can use the links here to get help, keep up to date with news around add-ons, and give us feedback.