MozillaWiki

WebExtensions: Difference between revisions

(Remove the list of unsupported APIs, we are maintaining that on MDN as well)
(added link to FAQ page)
 
(32 intermediate revisions by 10 users not shown)
Line 1: Line 1:
This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API. The goals of this API are:
'''If you are looking for documentation on how to develop an extension with WebExtensions APIs with Firefox, [https://developer.mozilla.org/en-US/Add-ons/WebExtensions please check out MDN].'''
 
This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API; a cross-browser system for developing extensions. The goals of this API are:
* Porting add-ons to and from other browsers should be easier.  
* Porting add-ons to and from other browsers should be easier.  
* Reviewing add-ons for addons.mozilla.org should be easier.
* Reviewing add-ons for addons.mozilla.org (AMO) should be easier.
* WebExtensions must be compatible with multiprocess Firefox ([[Electrolysis]]).
* Compatibility with multiprocess Firefox ([[Electrolysis]]).
* Changes to Firefox's internal code should be less likely to break add-ons.
* Changes to Firefox's internal code should be less likely to break add-ons.
* WebExtensions should be easier to use than the existing Firefox XPCOM/XUL APIs.
* WebExtensions APIs should be easier to use than the existing Firefox XPCOM/XUL APIs.
* WebExtensions APIs should maintain acceptable security and privacy standards.


Much of the specifics of the new API are similar to the Blink extension API. Google has [https://developer.chrome.com/extensions extensive documentation on the API]. [https://dev.opera.com/extensions/ So does Opera].
Much of the specifics of the new API are similar to the Blink extension API. Google has [https://developer.chrome.com/extensions extensive documentation on the API]. [https://dev.opera.com/extensions/ So does Opera]. But the [https://developer.mozilla.org/en-US/Add-ons/WebExtensions Firefox docs on MDN] are the best.


Experimental WebExtensions support is now available in Firefox Nightly. We are looking for developer feedback as we fix bugs and expand the set of APIs that are available. We will be listening on https://discourse.mozilla-community.org/c/add-ons/development.
'''Please note:''' the API is called "WebExtensions" because it can be found in search engines; "Web Extensions" (with a space) does not yield relevant results. Information on terminology usage is available [[Add-ons/Terminology|here]].
 
'''Please note:''' we are going with the name WebExtensions because it can be used in search engines, not Web Extensions (with a space) which is almost impossible to search.


== Status ==
== Status ==


* Bugs are filed in Bugzilla under Toolkit > WebExtensions, [https://bugzilla.mozilla.org/enter_bug.cgi?product=Toolkit&component=WebExtensions create a bug]
* Bugs are filed in Bugzilla under WebExtensions, [https://bugzilla.mozilla.org/enter_bug.cgi?format=guided#h=dupes%7CWebExtensions find or create a bug]


=== Road map ===
=== Useful queries ===
A draft road map is available [[WebExtensions/RoadMap|here]].
* [https://bugzilla.mozilla.org/buglist.cgi?f1=keywords&list_id=13314909&o1=anywords&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=dev-doc-needed&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Need documentation]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314901&o1=substring&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=triaged&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Triaged]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&o3=notsubstring&list_id=13314898&v3=intermittent-failure&o1=notsubstring&resolution=---&o2=notsubstring&query_format=advanced&f3=keywords&f2=status_whiteboard&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=triaged&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&v2=design-decision-needed&product=WebExtensions Untriaged] (note: this is different from the untriaged component)
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314907&o1=anywordssubstr&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=design-decision-needed&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Design Decision Needed]
* [https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=13314907&o1=anywordssubstr&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&v1=advisory-group&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Advisory Group]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13314906&resolution=---&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions All bugs]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13315397&resolution=FIXED&chfieldto=Now&query_format=advanced&chfield=cf_last_resolved&chfieldfrom=-17d&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions Closed in past 17 days]


=== First release ===
==== Firefox 57 ====
* We are working towards a 1.0 release of WebExtensions (which also means defining precisely what 1.0) means.
* But [https://bugzilla.mozilla.org/show_bug.cgi?id=1214433 1214433] is the tracker for the first release.
* You can also use the flags: '''blocks-webextensions''' to nominate a bug to be blocking that first release.
** Bugs [http://bit.ly/blocking-webextensions that block]
** Bugs [http://bit.ly/not-blocking-webextensions that do not block]
** Bugs [http://bit.ly/nominated-blocking-webextensions that have been nominated]


=== Useful queries ===
To keep track of priorities for Firefox 57, we are using the webextensions tracking flag. You can nominate a bug by using the flag with a ?. Bugs that are not on the tracking flag may still be worked but, but will not be a priority. All bugs must have a priority and preferably an assignee. All P1 bugs must have an assignee.
* Bugs that [http://bit.ly/web-extensions-documentation-needed currently need documentation]
 
* Bugs that [https://bugzilla.mozilla.org/buglist.cgi?f1=keywords&list_id=12836382&o1=anywords&o2=anywords&query_format=advanced&f2=flagtypes.name&bug_status=RESOLVED&bug_status=VERIFIED&bug_status=CLOSED&v1=dev-doc-needed&component=WebExtensions&v2=blocking-webextensions%2B&product=Toolkit currently need documentation and are blocking 1.0]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13377474&o1=equals&v1=%2B&f1=cf_blocking_webextensions&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions webextensions+]
*[https://bugzilla.mozilla.org/buglist.cgi?f1=flagtypes.name&o1=anywords&resolution=---&query_format=advanced&v1=blocking-webextensions%2B&list_id=12737558 web extensions target for Fx48]
* [https://bugzilla.mozilla.org/buglist.cgi?list_id=13377455&o1=equals&v1=%3F&f1=cf_blocking_webextensions&query_format=advanced&bug_status=UNCONFIRMED&bug_status=NEW&bug_status=ASSIGNED&bug_status=REOPENED&component=Android&component=Compatibility&component=Developer%20Tools&component=Experiments&component=Frontend&component=General&component=Request%20Handling&component=Untriaged&product=WebExtensions webextensions?]
*[https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=12810463&o1=substring&resolution=---&query_format=advanced&v1=triaged&component=WebExtensions&product=Toolkit Triaged bugs] ***under Toolkit::webextensions in bugzilla
**have '''triaged''' at the end of the Whiteboard
**'''blocking-webextensions''' flag has been set if a milestone 48 target)
*[https://bugzilla.mozilla.org/buglist.cgi?f1=status_whiteboard&list_id=12810465&o1=notsubstring&resolution=---&query_format=advanced&v1=triaged&component=WebExtensions&product=Toolkit Untriaged webextension bugs]
* [https://bugzilla.mozilla.org/buglist.cgi?resolution=---&query_format=advanced&component=WebExtensions&product=Toolkit&list_id=12695583 All bugs]


== Communication and meetings ==
== Communication and meetings ==


=== Meetings ===
* There is a [[Add-ons/Projects#New_WebExtension_APIs|list of prioritized WebExtension APIs]] publicly available as part of [[Add-ons/Projects|ongoing Add-ons work]].
 
* There are [https://wiki.mozilla.org/Add-ons/developer/communication developer resources] to help you through the migration.
* Checkout the [[Add-ons|Add-ons]] team page.
* Currently every week there is a [https://wiki.mozilla.org/Add-ons/developer/communication#Add-on_Developer_Communication_Calendar public triage meeting] of the bugs we hope to complete.
* Add the [https://calendar.google.com/calendar/embed?src=mozilla.com_ofjlct07k1784v1u51bqk476bk%40group.calendar.google.com&ctz=America/Los_Angeles Developer Communication Calendar] to get important dates, meetings, office hours, blog posts, and more.
* Every week there is a [https://wiki.mozilla.org/WebExtensions/Triage triage of WebExtensions APIs].
**[https://calendar.google.com/calendar/ical/mozilla.com_ofjlct07k1784v1u51bqk476bk%40group.calendar.google.com/public/basic.ics iCal] | [https://calendar.google.com/calendar/embed?src=mozilla.com_ofjlct07k1784v1u51bqk476bk%40group.calendar.google.com&ctz=America/Los_Angeles HTML]
* Join the mailing list at [https://mail.mozilla.org/listinfo/dev-addons dev-addons@mozilla.org].
* Currently every second week there is a public triage meeting of the bugs we hope to complete.
* Follow dev-addons
 
* Join us on [[IRC|IRC]] at #webextensions or #addons
* Join us on [[IRC|IRC]] at #webextensions or #addons
* Or join the mailing list at [https://mail.mozilla.org/listinfo/dev-addons dev-addons@mozilla.org].
* Again follow the [[Add-ons|Add-ons]] team page for more.


== Testing out the WebExtensions API ==
== Testing WebExtensions APIs ==


See [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Your_first_WebExtension Your first WebExtension] on MDN.
See [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Your_first_WebExtension Your first extension] on MDN.


= Technical Details =
= Technical Details =
Line 59: Line 50:
== Permission Model ==
== Permission Model ==


We currently enforce [https://developer.chrome.com/extensions/declare_permissions manifest permissions] for [[WebExtensions#List_of_supported_APIs|the supported APIs]]. We also don't enforce the CSP protections at all. Support for that is planned.
We currently enforce [https://developer.chrome.com/extensions/declare_permissions manifest permissions] for [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/API the supported APIs]. We also enforce CSP protections.


== Namespacing ==
== Namespacing ==


At this time, all APIs are accessible through the chrome.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace. Developers will be able to use feature detection to determine if an API is available in browser.*.
At this time, all APIs are accessible through the chrome.* and browser.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace.  


== Out-of-process Extensions ==
== Out-of-process Extensions ==


WebExtensions are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually.
Extensions developed with WebExtensions APIs are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually, see {{Bugzilla|1190679}} for more details.


== Packaging ==
Technical details about the implementation are published at [[WebExtensions/Implementing_APIs_out-of-process]].


Extensions are packaged as standard Zip files, but with <code>.xpi</code> extensions. In the future, we're planning to use the <code>.zip</code> extension instead.
Testing details are published at [[WebExtensions/Testing-out-of-process]].


The <code>manifest.json</code> file supports the following directives, in addition to the directives supported by Blink:
== Packaging ==


<blockquote><pre>
Extensions are packaged as standard Zip files, but with <code>.xpi</code> extensions. In the future, we're planning to move towards what the W3C WG recommends.
"applications": {
  "gecko": {
    "id": "{the-addon-id}",
    "strict_min_version": "40.0.0",
    "strict_max_version": "50.*"
    "update_url": "https://foo/bar"
  }
}
</pre></blockquote>


Both version fields are Gecko versions, and allow extension to support any application built on that version of Gecko. In the case of Firefox, they correspond to the Firefox release version.
See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives.


The <code>update_url</code> field may point to an [https://developer.mozilla.org/en-US/docs/Extension_Versioning,_Update_and_Compatibility#Update_RDF_Format RDF update manifest] to allow automatic updates.
== API support status ==


In the future, we hope to make all of these properties optional (which will require generating a unique ID upon installation or upload to addons.mozilla.org).
The list of APIs and their status is now maintained on [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities MDN]. We intend to fix any of the exceptions listed there.


See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives. Of these, we currently support the following:
== Additional APIs ==


* name
*If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of [https://mzl.la/2dVs5Ys approved APIs] that you can start contributing to.
* version
* description
* content_scripts
* permissions
* web_accessible_resources
* background
* browser_action
* default_locale


== API support status ==
*If you'd like to become familiar with Mozilla infrastructure so you can develop WebExtensions APIs directly for Firefox, follow these steps:
**Familiarize yourself with the on-boarding materials: [http://areweeveryoneyet.org/onramp/desktop.html Onboard to Firefox codebase]
**Pick a [https://bugzilla.mozilla.org/buglist.cgi?quicksearch=product%3AWebExtensions%20keyword%3Agood-first-bug&list_id=13160623 "Good First Bug"] to work on


The list of APIs and their status is now maintained on [https://developer.mozilla.org/en-US/Add-ons/WebExtensions/Chrome_incompatibilities MDN]. We intend to fix any of the exceptions listed there.
*If you just want to tinker with WebExtensions APIs without having to build Firefox, [http://webextensions-experiments.readthedocs.io/en/latest/index.html WebExtensions Experiments] is for you!


Please see [http://arewewebextensionsyet.com arewewebextensionsyet.com] for an up to date list of supported APIs that is taken by parsing schemas defined in mozilla-central.
*If you simply want to request a WebExtensions API, please [[WebExtensions/NewAPIs|read this information]] before filing a bug.


== Additional APIs ==
== Contributing ==


We plan to add our own APIs based on the needs of existing Firefox add-ons. We also want to hear from you! Please fill out [http://bit.ly/webextensions-apis this survey] to tell us which APIs you need.
Please see the [[WebExtensions/Hacking|hacking guide]] for information about contributing code to the WebExtensions project.


* NoScript-type functionality. This would come in the form of extensions to webRequest and possibly contentSettings.
Please see https://webextensions-experiments.readthedocs.io/en/latest/ for some information on Experiments which might be useful for contributing.
* Sidebars. Opera already supports sidebar functionality; Chrome may soon. We would like to be able to implement Tree Style Tabs or Vertical Tabs by hiding the tab strip and showing a tab sidebar.
* Toolbars. Firefox has a lot of existing toolbar add-ons.
* Better keyboard shortcut support. We'd like to support Vimperator-type functionality.
* Ability to add tabs to about:addons.
* Ability to modify the tab strip (Tab Mix Plus).
* Ability to take images of frames/tabs (like canvas.drawWindow)


== Contributing ==
Here is a list of all [https://wiki.mozilla.org/Add-ons/Contribute add-on contribution opportunities].


Please see the [[WebExtensions/Hacking|hacking guide]] for information about contributing code to the WebExtensions project.
== Frequently-Asked Questions ==
You can find more information about WebExtensions on [[WebExtensions/FAQ|our FAQ page]].

Latest revision as of 02:11, 5 September 2018

If you are looking for documentation on how to develop an extension with WebExtensions APIs with Firefox, please check out MDN.

This page is an introduction to Mozilla's implementation of WebExtensions, a new browser extension API; a cross-browser system for developing extensions. The goals of this API are:

  • Porting add-ons to and from other browsers should be easier.
  • Reviewing add-ons for addons.mozilla.org (AMO) should be easier.
  • Compatibility with multiprocess Firefox (Electrolysis).
  • Changes to Firefox's internal code should be less likely to break add-ons.
  • WebExtensions APIs should be easier to use than the existing Firefox XPCOM/XUL APIs.
  • WebExtensions APIs should maintain acceptable security and privacy standards.

Much of the specifics of the new API are similar to the Blink extension API. Google has extensive documentation on the API. So does Opera. But the Firefox docs on MDN are the best.

Please note: the API is called "WebExtensions" because it can be found in search engines; "Web Extensions" (with a space) does not yield relevant results. Information on terminology usage is available here.

Status

Useful queries

Firefox 57

To keep track of priorities for Firefox 57, we are using the webextensions tracking flag. You can nominate a bug by using the flag with a ?. Bugs that are not on the tracking flag may still be worked but, but will not be a priority. All bugs must have a priority and preferably an assignee. All P1 bugs must have an assignee.

Communication and meetings

Testing WebExtensions APIs

See Your first extension on MDN.

Technical Details

Permission Model

We currently enforce manifest permissions for the supported APIs. We also enforce CSP protections.

Namespacing

At this time, all APIs are accessible through the chrome.* and browser.* namespace. When we begin to add our own APIs, we expect to add them to the browser.* namespace.

Out-of-process Extensions

Extensions developed with WebExtensions APIs are compatible with Electrolysis. They run in the main Firefox process (except for content scripts, which run in the same process as web content). We are considering a plan to run extensions in a separate process (or possibly the content process) eventually, see 1190679 for more details.

Technical details about the implementation are published at WebExtensions/Implementing_APIs_out-of-process.

Testing details are published at WebExtensions/Testing-out-of-process.

Packaging

Extensions are packaged as standard Zip files, but with .xpi extensions. In the future, we're planning to move towards what the W3C WG recommends.

See https://developer.chrome.com/extensions/manifest for a complete list of manifest directives.

API support status

The list of APIs and their status is now maintained on MDN. We intend to fix any of the exceptions listed there.

Additional APIs

  • If you're experienced with Mozilla infrastructure and would like to develop WebExtensions APIs directly for Firefox, here is a list of approved APIs that you can start contributing to.
  • If you'd like to become familiar with Mozilla infrastructure so you can develop WebExtensions APIs directly for Firefox, follow these steps:

Contributing

Please see the hacking guide for information about contributing code to the WebExtensions project.

Please see https://webextensions-experiments.readthedocs.io/en/latest/ for some information on Experiments which might be useful for contributing.

Here is a list of all add-on contribution opportunities.

Frequently-Asked Questions

You can find more information about WebExtensions on our FAQ page.

Retrieved from "https://wiki.allizom.org/index.php?title=WebExtensions&oldid=1200562"