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.
Quick start
- 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.
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.
Partial migration
An Embedded WebExtension is an extension that combines two types of extensions in one, by incorporating a WebExtension inside of a bootstrapped or SDK extension. If you have a legacy extension that writes data to the filesystem, and you’re planning to port it to WebExtensions, Embedded WebExtensions are available to help you transition. Embedded WebExtensions can be used to transfer the stored data of your add-on to a format that can be used by WebExtensions. This is essential because it lets you to convert your users without the need for them to take any actions.
It’s important to emphasize that Embedded WebExtensions are intended to be a transition tool, and will not be supported past Firefox 57. They should not be used for add-ons that are not expected to transition to WebExtensions.
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.
- Lookup tool to check your add-on type and get porting resource recommendations
- 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
Documentation
- 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
Contact
-
You can use the links here to get help, keep up to date with news around add-ons, and give us feedback.