Copy as Markdown
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,
The implementation of a WebExtension API runs with
:doc:`chrome privileges </dom/scriptSecurity/index>`.
Browser internals are accessed using
or :doc:`ChromeOnly WebIDL features </dom/webIdlBindings/index>`.
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 <https://wiki.mozilla.org/WebExtensions/Vision>`_
- `API Policies <https://wiki.mozilla.org/WebExtensions/policy>`_
- `Process for creating new APIs <https://wiki.mozilla.org/WebExtensions/NewAPIs>`_
Many WebExtension APIs are accessed directly from extensions through
Regardless of the exact method by which something is exposed,
there are a few important considerations when designing part of an API
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
uses a namespace called ``tabs``, so all its functions and other
properties appear on the object ``browser.tabs``.
is to create a new namespace with a concise but descriptive name.
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 |getURL|_.
in which of these environments the feature will be available.
other environments have limited sets of API features available.
.. |getURL| replace:: ``browser.runtime.getURL()``
include an appropriate permission in the manifest.
The guidelines for when an API feature requires a permission are
described in (*citation needed*).
used feature in WebExtension APIs.
New API functions are asynchronous, returning a
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
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
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 <https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Structured_clone_algorithm>`_.
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.
can also take actions based on the contents of particular properties
in an extension's manifest (or even just the presence of a particular
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
`browser action <https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API/browserAction>`_
API for an example.
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 :ref:`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.