WebExtensions

This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API. The goals of this API are:

• Porting add-ons to and from other browsers should be easier.
• Reviewing add-ons for addons.mozilla.org should be easier.
• WebExtensions must be compatible with multiprocess Firefox (Electrolysis).
• Changes to Firefox's internal code should be less likely to break add-ons.
• WebExtensions should be easier to use than the existing Firefox XPCOM/XUL APIs.

Much of the specifics of the new API are similar to the Blink extension API. Google has extensive documentation on the API. So does Opera.

Experimental WebExtensions support is now available in Firefox Nightly. We are looking for developer feedback as we fix bugs and expand the set of APIs that are available. We will be listening on https://discourse.mozilla-community.org/c/add-ons/development. We do not yet support publishing WebExtensions to addons.mozilla.org. We hope to have that in place in a few weeks.

Testing out the WebExtensions API

First, you need to set up Firefox:

• download, install, and launch Firefox Nightly (Developer Edition also includes WebExtension support, but Nightly will always be more up-to-date).
• flip the preference that controls whether Firefox allows you to install unsigned add-ons:
  • type about:config into the URL bar in Firefox
  • in the Search box type xpinstall.signatures.required
  • double-click the preference, or right-click and selected "Toggle", to set it to false.

Example WebExtension

To help get you started, we've created a very simple example WebExtension at https://github.com/mdn/webextensions-examples. Clone this repo and navigate to the "borderify" directory.

 git clone https://github.com/mdn/webextensions-examples
 cd webextensions-examples/borderify/

This directory contains two files: manifest.json and borderify.js.

Every WebExtension must contain a manifest.json file. This one looks like:

   {
     
     "manifest_version": 2,
     "name": "Borderify",
     "version": "1.0",
      
     "applications": {
       "gecko": {
         "id": "borderify@mozilla.org"
       }
     },
     
     "content_scripts": [
       {
         "matches": ["*://*.mozilla.org/*"],
         "js": ["borderify.js"]
       }
     ]
     
   }

• The first three keys are mandatory basic metadata.
• The next key, "applications", contains Firefox-specific information.
• The next key, "content_scripts", specifies a match-pattern and a content script to run in matching pages. In this case the pattern matches any pages under mozilla.org, or any of its subdomains. The content script is "borderify.js".

The other file is borderify.js itself, which just draws a red border around the document body:

   document.body.style.border = "5px solid red";

Packaging

Firefox add-ons are packaged as XPI files, which are just ZIP files with an "xpi" extension.

One trick is that the ZIP file must be a ZIP of the files in the add-on, not of the containing directory. So to create an XPI from the borderify files, at the command prompt type, from inside the borderify directory, type:

   # in webextensions-examples/borderify/
   zip -r ../borderify.xpi *

Installing

To install the XPI, you can just open it in Firefox:

• from the File Menu, select Open, or press Ctrl/Cmd+O
• select borderify.xpi from the file selection dialog

You should get a warning that you are installing an unsigned extension. Accept the warning.

Now navigate to a page that matches, such as https://developer.mozilla.org/. You should see a red border appear round the page.

Experimenting

Try experimenting:

• change the match-pattern to match different pages.
• change "borderify" to do something else to the page.
• use a different API to make the add-on do something else.

Each time you change the add-on, you'll need to repeat the #Packaging and #Installing sections above. However, we're working on a feature that will enable Firefox to load an updated extension directly from its directory. See bug 1185460.

At this time, it is not possible to publish WebExtensions to addons.mozilla.org.

Technical Details

Permission Model

We currently enforce manifest permissions. However, we don't yet support the activeTab permission. We also don't enforce the CSP protections at all. Support for that is planned.

Namespacing

At this time, all APIs are accessible through the chrome.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace. Developers will be able to use feature detection to determine if an API is available in browser.*.

Out-of-process Extensions

WebExtensions are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually.

Packaging

Extensions are packaged as standard Zip files, but with .xpi extensions. In the future, we're planning to use the .zip extension instead.

The manifest.json file supports the following directives, in addition to the directives supported by Blink:

"applications": {
  "gecko": {
    "id": "{the-addon-id}",
    "strict_min_version": "40.0.0",
    "strict_max_version": "50.*"
    "update_url": "https://foo/bar"
  }
}

Both version fields are Gecko versions, and allow extension to support any application built on that version of Gecko. In the case of Firefox, they correspond to the Firefox release version.

The update_url field may point to an RDF update manifest to allow automatic updates.

In the future, we hope to make all of these properties optional (which will require generating a unique ID upon installation or upload to addons.mozilla.org).

See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives. Of these, we currently support the following:

• name
• version
• description
• content_scripts
• permissions
• web_accessible_resources
• background
• browser_action
• default_locale

List of supported APIs

The following APIs are fully or partially supported. We intend to fix any of the exceptions listed below. This list is now maintained on [MDN](https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities).

List of APIs we will likely support in the future

• bookmarks
• commands
• contextMenus
• cookies
• Devtools (mostly panels)
• downloads
• history
• idle
• omnibox
• pageAction
• permissions
• Native messaging (runtime.connectNative)

Additional APIs

We plan to add our own APIs based on the needs of existing Firefox add-ons.

• NoScript-type functionality. This would come in the form of extensions to webRequest and possibly contentSettings.
• Sidebars. Opera already supports sidebar functionality; Chrome may soon. We would like to be able to implement Tree Style Tabs or Vertical Tabs by hiding the tab strip and showing a tab sidebar.
• Toolbars. Firefox has a lot of existing toolbar add-ons.
• Better keyboard shortcut support. We'd like to support Vimperator-type functionality.
• Ability to add tabs to about:addons.
• Ability to modify the tab strip (Tab Mix Plus).
• Ability to take images of frames/tabs (like canvas.drawWindow)