WebExtensions/FAQ

Understanding the WebExtensions API

What is an extension?

An extension is a structured collection of web development code (JavaScript, HTML, CSS) that modifies the behavior or appearance of the Firefox browser. Extensions have been a part of Firefox for many years and allow users to customize their browsing experience.

What is the WebExtensions API?

WebExtensions is the name of the API used to write extensions for Firefox. Large portions of it are compatible with the API for Chrome, Opera and MS Edge so that extensions can more easily be created and used across browser platforms.

Developing with the WebExtensions API

What skills are needed to write an extension with the WebExtensions API?

If you know HTML, CSS and some JavaScript, you have all the necessary skills to write a Firefox extension. The WebExtensions API is designed to be easily understood and used by anyone using modern web development tools.

I want to write an extension. Where do I start?

The MDN web docs site has an entire section dedicated to extension development with the WebExtensions API. It provides a quick overview to get you started as well as complete reference documentation for the entire WebExtensions API.

Are WebExtension API compatible with multiprocess Firefox?

Yes, all APIs work with multiprocess Firefox and are marked as compatible by default. No special development steps are needed.

Does the WebExtensions API provide access to preferences?

No. Direct access to preferences in the past has caused many problems. Multiple extensions would try to change them and conflict, and the lack of security limitations meant malicious extensions were able to take advantage of users. Instead, WebExtensions focus on higher level APIs that implement specific tasks. Those APIs may subsequently alter preferences, but the WebExtension API would manage that behind the scenes, the developer would not set them directly.

How can I distribute my extension?

The Publishing and Distributing section of MDN provides a complete guide to getting your extension approved and published.

WebExtension Roadmap

Is the WebExtensions API a Web standard?

Not yet. Working through a W3C charter group, Mozilla has partnered with Microsoft and Opera to define a browser extension API that works across multiple browsers. There is currently a preliminary specification that matches what Google has implemented in Chrome so that extensions written to the specification could potentially work on Chrome, Edge, Opera and Firefox. For the moment, however, there are still differences between browsers that developers need to be aware of. The preliminary specification defines the browser extension namespace as “browser” whereas Chrome defines it as “chome.” Firefox supports both namespaces in order to enable a larger population of current extensions. In addition, a WebExtensions polyfill exists that will allow extensions written to the preliminary specification to work in Chrome.

Is WebExtensions a stable API?

Yes. Each API will be documented on MDN in regards to its standards and/or experimental status. APIs that are deprecated will also be noted. More details on how to understand the status of the WebExtensions API can be found on the wiki page.

Are there WebExtension API outside of the draft specification?

Yes. Unlike the web platform, we don't expect every browser to implement every aspect of WebExtensions in the same way. However, even without perfect overlap between browsers, a common API still has many advantages for extension developers. If developers stay within the common API, their extensions should work with minimal (or no) modifications across browsers. Even if developers choose to use browser-specific APIs, their extensions may be usable on other browsers through feature detection and fallbacks.

Can I propose a new API for WebExtensions?

Absolutely, and we encourage you to do so. Before starting, consider whether your proposed API fits within the WebExtensions API Policy. If it does, file a bug in Bugzilla under Toolkit -> WebExtensions: Untriaged. This allows the proposal to be reviewed by the WebExtensions development team. To make the decision process as transparent as possible, we hold a public triage of these bugs every other week. Each one is labeled "design needed", "approved", or "rejected".

Can I prototype a new WebExtensions API?

Yes. WebExtension Experiments allow you to expose and test almost any feature as a new WebExtensions API without having to build Firefox. It can help you understand how an API might work and what its limitations might be. Prototype WebExtension experiments can be run in the Firefox Nightly build. Keep in mind, though, that the existence of an experiment doesn’t guarantee that the feature will ultimately become an official WebExtension API.

WebExtension API and Legacy Extensions

When did Firefox adopt the WebExtensions API?

In August of 2015, Mozilla announced that the legacy XPCOM- and XUL-based extension systems would be deprecated in favor of the WebExtension API. Between that date and November, 2017, both legacy and WebExtension add-ons were supported in some fashion. With the release of Firefox 57 (Quantum) in November, 2017, WebExtensions became the only supported API for extension development.

Doesn’t Firefox use XUL internally?

There are parts of Firefox that continue to use XUL internally. Over time, though, XUL is being actively replaced with newer, more modern technologies. For example, starting with release 57 (Quantum), Firefox has an entirely new CSS engine. The WebExtensions API creates a layer of abstraction between an extension and the internal technologies used by Firefox. Extensions that depended on Firefox's usage of XUL would eventually break as XUL is progressively removed from the product.

Did Firefox copy Google Chrome?

The goal of the WebExtensions API was not to simply copy Chrome or even allow Chrome extensions to run unmodified in Firefox, but to simplify cross-browser development by providing commonly-supported methods and interfaces. To deny that Chrome had a very large market share and a modern, supportable extension ecosystem would have been foolish. Providing open, cross-platform interoperability on the web is central to Mozilla’s mission, so modeling the WebExtensions API on Chrome’s existing API made the most sense for the internet. That said, each vendor will have certain API that only apply to their own browsers.

Why WebExtensions and not Jetpack?

The WebExtensions API has some inherent technology advantages, such as built-in support for content blocking used by popular ad-blocking extensions, that Jetpack lacked. More importantly, though, basing the initial implementation of WebExtensions on Chrome's API meant that Firefox could leverage a large population of Chrome extensions (larger than Jetpack add-ons) and extension developers. Those developers who stayed with the common APIs were also able to work off of a common codebase, and port extensions more simply between browsers.

Why keep the .xpi packaging format?

Firefox uses JAR signing for WebExtensions while Chrome uses a different system. Since signing is necessarily browser-specific, integrating the two would be difficult, and maintaining the current packaging extension for Firefox makes sense. The only part of the XPI file format that WebExtensions uses is the filename suffix.

Were malicious add-ons really a problem?

Yes. Please read The Case for Extension Signing.