Background

WebExtensions run in a sandboxed environment much like regular web content. The purpose of extensions is to enhance the browser in a way that regular content cannot – WebExtensions APIs bridge this gap by exposing browser features to extensions in a way preserves safety, reliability, and performance. The implementation of a WebExtension API runs with chrome privileges. Browser internals are accessed using XPCOM or ChromeOnly WebIDL features.

The rest of this documentation covers how API implementations interact with the implementation of WebExtensions. To expose some browser feature to WebExtensions, the first step is to design the API. Some high-level principles for API design are documented on the Mozilla wiki:

• Vision for WebExtensions

• API Policies

• Process for creating new APIs

Javascript APIs

Many WebExtension APIs are accessed directly from extensions through Javascript. Functions are the most common type of object to expose, though some extensions expose properties of primitive Javascript types (e.g., constants). Regardless of the exact method by which something is exposed, there are a few important considerations when designing part of an API that is accessible from Javascript:

• Namespace: Everything provided to extensions is exposed as part of a global object called browser. For compatibility with Google Chrome, many of these features are also exposed on a global object called chrome. Functions and other objects are not exposed directly as properties on browser, they are organized into namespaces, which appear as properties on browser. For example, the tabs API uses a namespace called tabs, so all its functions and other properties appear on the object browser.tabs. For a new API that provides features via Javascript, the usual practice is to create a new namespace with a concise but descriptive name.

• Environments: There are several different types of Javascript environments in which extension code can execute: extension pages, content scripts, proxy scripts, and devtools pages. Extension pages include the background page, popups, and content pages accessed via browser.runtime.getURL(). When creating a new Javascript feature the designer must choose in which of these environments the feature will be available. Most Javascript features are available in extension pages, other environments have limited sets of API features available.

• Permissions: Many Javascript features are only present for extensions that include an appropriate permission in the manifest. The guidelines for when an API feature requires a permission are described in (citation needed).

The specific types of features that can be exposed via Javascript are:

• Functions: A function callable from Javascript is perhaps the most commonly used feature in WebExtension APIs. New API functions are asynchronous, returning a Promise. Even functions that do not return a result use Promises so that errors can be indicated asynchronously via a rejected Promise as opposed to a synchronously thrown Error. This is due to the fact that extensions run in a child process and many API functions require communication with the main process. If an API function that needs to communicate in this way returned a synchronous result, then all Javascript execution in the child process would need to be paused until a response from the main process was received. Even if a function could be implemented synchronously within a child process, the standard practice is to make it asynchronous so as not to constrain the implementation of the underlying browser feature and make it impossible to move functionality out of the child process. Another consequence of functions using inter-process communication is that the parameters to a function and its return value must all be simple data types that can be sent between processes using the structured clone algorithm.

• Events: Events complement functions (which allow an extension to call into an API) by allowing an event within the browser to invoke a callback in the extension. Any time an API requires an extension to pass a callback function that gets invoked some arbitrary number of times, that API method should be defined as an event.

Manifest Keys

In addition to providing functionality via Javascript, WebExtension APIs can also take actions based on the contents of particular properties in an extension’s manifest (or even just the presence of a particular property). Manifest entries are used for features in which an extension specifies some static information that is used when an extension is installed or when it starts up (i.e., before it has the chance to run any code to use a Javascript API). An API may handle a manifest key and implement Javscript functionality, see the browser action API for an example.

Other Considerations

In addition to the guidelines outlined above, there are some other considerations when designing and implementing a WebExtension API:

• Cleanup: A badly written WebExtension should not be able to permanently leak any resources. In particular, any action from an extension that causes a resource to be allocated within the browser should be automatically cleaned up when the extension is disabled or uninstalled. This is described in more detail in the section on Managing the Extension Lifecycle.

• Performance: A new WebExtension API should not add any new overhead to the browser when the API is not used. That is, the implementation of the API should not be loaded at all unless it is actively used by an extension. In addition, initialization should be delayed when possible – extensions ared started relatively early in the browser startup process so any unnecessary work done during extension startup contributes directly to sluggish browser startup.