META: background scripting

[carlosjeurissen]

To allow extensions to run tasks in the background when no UI is visible to the user or bound to be too insecure (like content_scripts), browsers provide the ability to run scripts in the background. The way this can be achieved has changed over time as shown below.

MV1 syntax (background_page)

MV1 only supported a persistent background page which you could define with the background_page property. This has been replaced with the background property in MV2.

MV2 syntax (background.scripts)

Manifest v2 introduced the background property which allows to define the background page using an object notation like this:

"background": {
  "page": "/background.html"
}

In addition to defining the page, it introduced the background.scripts property which allows the webExt author to define a set of scripts instead of a page. In which case the browser will generate the background page automatically and add the script tags to the body of the background page.

Then it introduced the background.persistent property. Which is true by default (needs confirmation by all browsers). This allows to either go for the classic background page, or opt in (by setting to false) to so called Event pages. These pages will only run when needed by the extension. See Chrome MV2 Docs.
Inconsistencies: the event pages are currently not supported by Firefox yet mandatory on iOS Safari. In macOS Safari < v14.1, only persistent pages were supported. In addition, Microsoft edge < v45 requires the persistent property to be set.

MV3 syntax (background.service_worker)

A new syntax has been proposed with MV3 to replace the background pages and scripts with background.service_worker. The other properties page, scripts and persistent are not accepted anymore. A new background.type property is introduced which can be set to "module" which allows you to import further code. See Chrome MV3 SW Docs. This new syntax is also supported in MV2 in Google Chrome starting in version xxx without flags. The service_worker can be killed at any time unlike the persistent background pages and lacks web APIs not available in serviceWorkers. Some webExt APIs are also unavailable like i18n.getMessage, see #93.

Group issues related to background.service_worker

As some may be aware there are quite some issues and incompatibilities when switching from background pages to serviceWorkers. A dedicated issue is made collecting all use cases not covered by serviceWorkers:

• Use cases that are not well served by service workers #72

Not included in this overview are:

• Challenging Service Worker Use Case - Machine Learning Models #73
• Dynamic data-driven Tracking Protection not possible with DNR #88
• Use cases that are not well served by service workers #72 (comment)
• Use cases that are not well served by service workers #72 (comment)
• Use cases that are not well served by service workers #72 (comment)
• Use cases that are not well served by service workers #72 (comment)
• Use cases that are not well served by service workers #72 (comment)
• Use cases that are not well served by service workers #72 (comment)

Proposals to improve the background.service_worker situation

• [Manifest V3] WebExtensionWorker instead of Service Worker #11
• Proposal for Manifest V3: add permission allowing a background script to be persistent #44
• Proposal: allow to use i18n.getMessage in a serviceWorker #93

Action items

• Consider changing the serviceWorker to a new webExtensionWorker. See [Manifest V3] WebExtensionWorker instead of Service Worker #11
• Consider allowing the serviceWorker to keep running in the background based on a new permission. See Proposal for Manifest V3: add permission allowing a background script to be persistent #44
• Consider keeping support for actual html-based background pages (MV2 syntax)
• Collect additional use cases not served by serviceWorkers and add them to Use cases that are not well served by service workers #72
• Consider accepting background.persistent: true in each browser even when event pages are mandatory. This allows webExt authors to use a single code base and use a persistent background page in other browsers. See Apple Forum post and Apple Feedback Assistent ticket.
• Figure out what browser versions start supporting background.service_worker in MV2
• Confirm if background.persistent is true by default in all browsers. And adding documentation for it.
• Consider allowing webRequestBlocking with background.persistent: false. See: Proposal: allow webRequest with background.persistent: false / SW #148
• Consider making the persistent property mandatory like in Microsoft edge < v45 so it's more clear what mode the background page is in.
• Update browserCompat on MDN to correct the fact edge > v44 doesn't require the persistent property anymore. See Background on MDN. Raised as Issue on browserCompat data