How do I migrate a legacy XPCOM extension to WebExtensions?

Question

Embedded WebExtensions talks all about how to "... embed a WebExtension in a classic bootstrapped extension or an Add-on SDK add-on."

But I've got neither a "bootstrapped" nor "Add-on SDK" extension, just a decade old plain old XPCOM/overlay extension. I don't have a bootstrap.js to have a startup, nor do I use the Add-on SDK for whatever it does.

I tried adding

<em:bootstrap>true</em:bootstrap>

But all that accomplishes is completely destroying the extension, it only loads that (empty) new bootstrap.js file.

Indeed, I want to migrate : The data that my classic extension has needs to be exported to the webext version, for good user experience.

Answer 1

At our tracking bug a user has posted a helpful link:

https://github.com/mdn/webextensions-examples/tree/master/embedded-webextension-overlay

Which boils down to

const {
  LegacyExtensionsUtils,
} = Components.utils.import("resource://gre/modules/LegacyExtensionsUtils.jsm");

const myOverlayEmbeddedWebExtension = LegacyExtensionsUtils.getEmbeddedExtensionFor({
  id: addonId, resourceURI: baseURI,
});

myOverlayEmbeddedWebExtension.startup().then(({browser}) => {
  dump(`${addonId} - embedded webext started\n`);
  browser.runtime.onMessage.addListener(msg => {
    dump(`${addonId} - received message from embedded webext ${msg}\n`);
  });
}).catch(err => {
  Components.utils.reportError(
    `${addonId} - embedded webext startup failed: ${err.message} ${err.stack}\n`
  );
});

Which is surely the equivalent of what the bootstrap/SDK code is doing for you.

Answer 2

You can only rewrite it from scratch using the WebExtension APIs.

Note that the WebExtensions model requires you only use the APIs explicitly exported for use by extensions, so prepare to drop some features during the rewrite, or even to find that it's impossible to reimplement the extension altogether (unless you convince Mozilla to implement the new APIs you need or implement it yourself in a WebExtension Experiment -- still limited to Nightly/Dev.edition).

See Porting a legacy Firefox extension

[edit] the "embedded WebExtension" does indeed require your "outer" extension to be bootstrapped or Add-on SDK-based (so no "classic" extensions), but it was only intended to be used for gradual migration and will not work in Firefox 57.

Answer 3

There is no convenient way to do this directly.

The most efficient way to do this is:

1. Rewrite your extension as a WebExtension. Get as much functional as possible, given the limits of WebExtensions.
2. Then, add a bootstrap or Add-on SDK (easier) wrapper which only transfers the data from your original overlay based extension. Thus, the bootstrap/Add-on SDK portion of the extension will be minimal, with it's only tasks being to start the WebExtension (each time the extension is loaded) and transfer the data (once).

While this won't permit the gradual migration into a WebExtension which was one of the supposed benefits of using embedded WebExtensions, it will permit you to migrate the data from your overlay extension to a WebExtensions based version.

You could transition it to bootstrapped/Add-on SDK first ➞ then embedded WebExtensions ➞ then full WebExtension, but that would be considerably more work, without any significant benefit.

Answer 4

One option that I suggest to the people in similar situations, is to provide an Export function in the current legacy addon and an Import in the WebExtension version. While it is not an automatic migration (has to be user action), it overcomes some of the limitations of the WebExtension local-file access.

Using the Export , users will be prompted to save their complete data to hard-disk.

Then the next upgrade which would be a WebExtension, prompts the users to Import the saved data.