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

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.