Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.
Starting from Firefox 53, no new legacy add-ons will be accepted on addons.mozilla.org (AMO) for desktop Firefox and Firefox for Android.
Starting from Firefox 57, WebExtensions will be the only supported extension type. Desktop Firefox and Firefox for Android will not load other extension types.
Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more information.
A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.
This article explains how an add-on developer can check whether their add-on is compatible with multiprocess Firefox, and if it isn't, how to fix it.
In older versions of Firefox, chrome code (including code inserted by extensions) and content run in the same operating system process. So extensions can access content directly:
gBrowser.selectedBrowser.contentDocument.body.innerHTML = "replaced by chrome code";
However, in multiprocess Firefox (also called Electrolysis or E10S), the extension's code will run in a different process from content, and this kind of direct access will no longer be possible.
Checking whether you're affected
You can use the Compatibility Lookup Tool to check if your add-on will be affected by these changes.
As a rule, you won't be affected if:
- you use the WebExtension API
- you only use the Add-on SDK's high-level APIs
- you don't access web content at all
- you load XUL content into tabs via chrome: URLs
You will be affected if:
- you access web content directly using an overlay extension, a bootstrapped extension, or low-level SDK APIs like window/utils or tabs/utils
For more details, see the article on Limitations of chrome scripts, which lists patterns that will no longer work in the chrome process.
Testing
In multiprocess Firefox, add-ons can run in two different modes: either with compatibility shims or without them. Add-ons are more likely to work with compatibility shims, but they will run much more slowly if they access web content often. Shims will be removed six months after multiprocess Firefox is released to users, so developers should avoid shims if possible.
Testing if your add-on works with shims: Make sure you're running Firefox Nightly, in which multiprocess support is enabled by default. To verify that multiple process are being used, visit about:support and confirm that the "Multiprocess Windows" row contains "default: true". (If you see a different value, open Firefox preferences and check "Enable multi-process Nightly" in the General pane.) Now install your add-on and test that all features work. If you're testing an unsigned version of your extension, make sure you turn signing enforcement off.
Testing if your add-on works without shims: As before, make sure you're running Firefox Nightly with multiple processes enabled. Next, add a new property to your extension's install.rdf named multiprocessCompatible, with a value of true. Now install your add-on and test that all features work.
The rest of this document explains how to make broken add-ons work in multiprocess Firefox without using shims.
Adapting to Multiple Processes
If your add-on is not multiprocess-compatible, the best solution is to rewrite your add-on as a WebExtension. WebExtensions APIs are compatible with multiprocess Firefox. WebExtensions are the future of Firefox add-ons: other types of add-on, including XUL overlay add-ons, bootstrapped add-ons, and SDK add-ons, are now considered deprecated. From version 57, Firefox will no longer load such add-ons.
- See a feature comparison between WebExtensions and the SDK.
- See a feature comparison between WebExtensions and XUL overlay/bootstrapped add-ons.
Note that WebExtensions don't give you all the same features that legacy add-ons do. However we are open to extending the WebExtension APIs to support the needs of add-on developers, so if you have ideas, we'd love to hear them. You can reach the WebExtensions team on the dev-addons mailing list or #webextensions on IRC.
If you can't port to WebExtensions yet, the Add-on SDK's high-level APIs are the next best choice. But note that this is not a future-proof solution, since SDK add-ons will not be supported from Firefox 57 onwards.
The last option is to use the message manager to communicate with the content process. The message manager can be used from the Add-on SDK or from overlay or bootstrapped add-ons.
- See how to use the message manager from the SDK.
- See how to use the message manager from overlay or bootstrapped add-ons.
Again, note that this is not a future-proof solution, since SDK, overlay, and bootstrapped add-ons will not be supported from Firefox 57 onwards.
If you need help, please contact us in the #addons channel at irc.mozilla.org. We're here to help!