Basics¶
WebExtensions Experiments provide a way for developers to tinker with new APIs for WebExtensions. They allow new WebExtensions APIs to be implemented in an extension. They can be used to prototype APIs for landing in Firefox, or for use on Nightly or Developer Edition.
Note
If you simply want to request a WebExtensions API, please see
this page on the Firefox wiki.
Note
If you’d like to land a WebExtensions API straight into Firefox, are familiar with building mozilla-central, working with Bugzilla, the try server, then please file a bug and follow the usual Firefox development process.
Overview¶
An experiment refers to all the code that implements some new
experimental WebExtension API. An experiment may be placed in its own
.xpi
file, or it may be bundled with an extension that uses it
(i.e., have all the experiment code contained in the same .xpi
file
as the extension that uses it).
Note
When experiments were originally created they used a format based on install.rdf
but this format is deprecated and should not be used.
Experiments allow you to:
- Test and experiment with an API without having to build Firefox at all.
- Write and distribute the API to a set of users without them having to build Firefox.
- Then commit to (or get help committing to) mozilla-central.
Note
We will not add all experiments to Firefox. The goal is to judge each Experiment on its own merit and value.
Some key points:
- The API is implemented in the experiment.
- The API is available in the browser namespace - not in chrome.
- Breaking changes could occur in the experiment, but are discouraged.
How do they work?¶
For general documentation about designing and developing WebExtension APIs, see the documentation at firefox-source-docs.mozilla.org.
If you prefer working examples, here are a few WebExtensions that use bundled experiments:
- Mike Conley’s ohnoreflow
- Rob Helmer’s crashme
Non-bundled Experiments¶
The documentation above explains how to create an experimental API that is
bundled with a WebExtension.
It is also possible to create a WebExtension that depends on
an experimental API contained in a different .xpi
file,
though we are considering removing this capability in a future release.
In the mean time, to create an extension that uses an experimental API from
a different extension, you must:
- Include an extension ID
in the manifest of the extension that contains the implementation of the API.
The ID must be of the form
name@experiments.addons.mozilla.org
wherename
is a string that identifies the experiment. - Include the string
"experiments.name"
in the permissions property in the manifest of any extension that will use the API. The stringname
must be replaced by the name in the ID of the extension that provides the API.
In this case, a user must manually install the experiment when they install the WebExtension that uses the experimental API. The WebExtension will be automatically disabled unless/until the experiment it depends on is installed and enabled.
Where do they work?¶
Currently experiments can only be loaded in Firefox Nightly and Firefox Developer Edition.
Please see the policy page.