Prototyping APIs with Firefox WebExtensions Experiments

This article provides a comprehensive overview of Firefox WebExtensions Experiments, a powerful toolkit that enables developers to design, build, and test new browser extension APIs directly within Firefox Nightly. It explains the core purpose of these experiments, the structural components required to build them, and the exact process by which they grant access to privileged browser internals for rapid API prototyping without needing to compile the Firefox source code.

What are WebExtensions Experiments?

WebExtensions Experiments are a specialized mechanism provided by Mozilla that allows developers to create experimental APIs for Firefox extensions. Standard WebExtensions are limited to a predefined set of secure, cross-browser APIs. When developers need functionality that does not yet exist in the standard WebExtensions API, they can use Experiments to bridge the gap.

Instead of downloading the massive Firefox source code, writing C++ or internal JavaScript, and compiling a custom browser build, developers can package their new API just like a standard browser extension. This drastically lowers the barrier to entry for contributing to Firefox's extension capabilities.

How They Enable Prototyping in Firefox Nightly

To maintain security for general users, standard releases of Firefox block extensions from accessing internal browser components. However, Firefox Nightly (and Developer Edition) includes switches that lift these restrictions, turning the browser into a sandbox for API development.

WebExtensions Experiments work in Nightly by allowing an extension to run privileged code—known as Chrome-privileged JavaScript. This code has unrestricted access to Firefox internals, including XPCOM components and internal JavaScript modules (JSMs).

To prototype an API in Firefox Nightly, a developer must configure the browser and structure their extension using three specific components.

1. Configuring Firefox Nightly

Before an experiment can run, Firefox Nightly must be configured to allow unsigned, privileged extensions. Developers must navigate to about:config in the browser and set the following preferences:

  • extensions.experiments.enabled set to true (Enables the Experiments feature).
  • xpinstall.signatures.required set to false (Allows installing the unverified prototype).

2. The API Schema (JSON)

The first technical component of an experiment is the Schema. Written in JSON, the schema defines the shape of the new API. It acts as a contract between the privileged browser internals and the unprivileged extension code. The schema specifies:

  • The namespace of the new API (e.g., browser.myNewApi).
  • The functions, events, and types that the API will expose.
  • The parameters those functions accept and the data types they return.

3. The API Implementation (JavaScript)

The implementation file is where the actual logic of the API lives. This JavaScript file runs in a privileged scope, meaning it can interact directly with the browser's UI, file system, and network layers.

When an extension calls a function defined in the JSON schema, the implementation file intercepts the call, executes the privileged Firefox internal code, and returns the result safely back to the standard extension environment.

4. The Manifest Declaration

To tie the schema and the implementation together, the developer must declare the experiment in the extension's manifest.json file using the experiment_apis key.

This section of the manifest tells Firefox Nightly what the API is named, where to find the JSON schema file, and which JavaScript file contains the privileged implementation code. Once loaded via the about:debugging page in Nightly, the new API becomes immediately available for use in the extension's background scripts or popups.

From Prototype to Production

WebExtensions Experiments are not meant for permanent distribution to end-users, as Mozilla will not sign extensions containing experimental APIs for standard Firefox releases. Instead, they serve as a proof-of-concept. Once a developer successfully prototypes an API in Nightly and proves its utility and security, they can submit their code to Mozilla via Bugzilla to be reviewed and potentially integrated directly into the official Firefox source code for all developers to use.