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 elsewhere (add links here).
Everything provided to extensions is exposed as part of a global object
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
extension code can execute: extension pages, content scripts, proxy
scripts, and devtools pages.
Extension pages include the background page, popups, and content pages
- 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.
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.