Multiprocess Firefox and the SDK

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, only extensions developed using WebExtensions APIs will be supported on Desktop Firefox and Firefox for Android.

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 use WebExtensions APIs if they can. See the "Compatibility Milestones" document for more information.

This article explains how developers can test whether SDK-based add-ons are compatible with multiprocess Firefox, and how to fix them if they are not.

The project to make Firefox multiprocess is also known as "electrolysis" or "e10s". For much more information, see the multiprocess Firefox pages.

Firefox is moving to a multiprocess architecture in which it uses one operating system process for the browser UI (also known as the chrome process), and another process to execute code running in web pages (also known as the content process).

The main compatibility consequence of this is that code running in the chrome process will no longer get direct access to web content.

Because SDK add-ons run in the chrome process (except for their content scripts):

The SDK contract

Low-level APIs might not work. If you're using low-level APIs, review your use of them, test, and potentially refactor.

In practice most low-level APIs will work fine, but low-level APIs that give direct access to web content will not work.

Testing your add-on

To ease the transition for add-on developers, we've provided add-ons with compatibility shims for many APIs. With these shims in place, code that you would not expect to work in multiprocess Firefox - for example, code that directly accesses web content - will still work.

These shims use wrappers called Cross Process Object Wrappers, to make it look as if code in one process can directly access objects in a different process.

However, these shims are just a temporary migration aid, not a permanent solution. You should aim to make your add-on work without the shims.

Also, the shims don't fix all possible problems, so even a shimmed add-on may not work with multiprocess Firefox.

For example: some add-ons, like ad-blockers, want to use nsIContentPolicy to register a content policy. In multiprocess Firefox, if you register the nsIContentPolicy in the chrome process then it will never see any attempts to load web content, because they happen in the content process. Instead, you must register the content policy in the content process.

SDK internal incompatibilities

Unfortunately, the SDK itself isn't completely multiprocess-compatible. This means that if you disable shims for your add-on, then it might not work, even if you are only using high-level APIs. For example:

This add-on will not work if you've set the "multiprocess" permission, because sdk/selection depends on the shims. If this is the case for you, there's nothing you can do to fix it apart from using a different API.

We're working on fixing these problems: see bug 1004745 and its dependencies.

Examples

Using nsIContentPolicy with "remote/parent"

This example shows how to use the "remote/parent" module to register a content policy in the content process.

The add-on consists of three files:

package.json

index.js

content-policy.js

Original version

In the original version, the "package.json" file can just be the default file generated by jpm init.

You can build this into an add-on, and it will work fine in singleprocess Firefox. In the Browser Console, you'll see messages being logged as you load pages.

Because we haven't set the "multiprocess" permission in package.json, it will work fine in multiprocess Firefox as well, because nsIContentPolicy is shimmed.

Ported version

First, set the "multiprocess" permission by adding a key like this in package.json:

"permissions": {
"multiprocess": true
}

Now try running the add-on in multiprocess Firefox. You should no longer see any output in the Browser Console, because you registered the content policy in the chrome process, but the loads are happening in the content process.