background

Type Object
Mandatory No
Manifest version 2 or higher
Example
json
"background": {
  "scripts": ["background.js"]
}

Use the background key to include one or more background scripts, a background page, or a Service worker in your extension.

Background scripts are the place to put code that needs to maintain a long-term state or perform long-term operations independently of the lifetime of any particular web pages or browser windows.

Background scripts are loaded as soon as the extension is loaded and stay loaded until the extension is disabled or uninstalled unless persistent is specified as false. You can use any WebExtension APIs in the script if you have requested the necessary permissions.

See Background scripts for some more details.

The background key is an object that must have one of these properties (for more information on how these properties are supported, see Browser support):

page

If you need specific content in the background page, you can define a page using the page property. This is a String representing a path relative to the manifest.json file to an HTML document included in your extension bundle.

If you use this property, you can not specify background scripts using scripts, but you can include scripts from the page, just like a normal web page.

scripts

An Array of Strings, each of which is a path to a JavaScript source. The path is relative to the manifest.json file itself. These are the scripts that are executed in the extension's background page.

The scripts share the same window global context.

The scripts are loaded in the order they appear in the array.

If you specify scripts, an empty page is created where your scripts run.

Note: If you want to fetch a script from a remote location with the <script> tag (e.g., <script src = "https://code.jquery.com/jquery-3.6.0.min.js">), you have to change the content_security_policy key in the manifest.json file of your extension.

service_worker

Specify a JavaScript file as the extension service worker. A service worker is a background script that acts as the extension's main event handler.

The background key can also contain this optional property:

persistent

A Boolean value.

If omitted, this property defaults to true in Manifest V2 and false in Manifest V3. Setting to true in Manifest V3 results in an error.

  • true indicates the background page is to be kept in memory from when the extension is loaded or the browser starts until the extension is unloaded or disabled, or the browser is closed (that is, the background page is persistent).
  • false indicates the background page may be unloaded from memory when idle and recreated when needed. Such background pages are often called Event Pages, because they are loaded into memory to allow the background page to handle the events to which it has added listeners. Registration of listeners is persistent when the page is unloaded from memory, but other values are not persistent. If you want to store data persistently in an event page, then you should use the storage API.
type

A String value.

Determines whether the scripts specified in "scripts" are loaded as ES modules.

  • classic indicates the background scripts or service workers are not included as an ES Module.
  • module indicates the background scripts or service workers are included as an ES Module. This enables the background page or service worker to import code.

If omitted, this property defaults to classic.

Browser support

Support for the scripts, page, and service_worker properties varies between browsers like this:

  • Chrome:
    • supports background.service_worker.
    • supports background.scripts (and background.page) in Manifest V2 extensions only.
    • before Chrome 121, Chrome refuses to load a Manifest V3 extension with background.scripts or background.page present. From Chrome 121, their presence in a Manifest V3 extension is ignored.
  • Firefox:
    • background.service_worker is not supported (see Firefox bug 1573659).
    • supports background.scripts (or background.page) if service_worker is not specified or the service worker feature is disabled. Before Firefox 120, Firefox did not start the background page if service_worker was present (see Firefox bug 1860304). From Firefox 121, the background page starts as expected, regardless of the presence of service_worker.
  • Safari:
    • supports background.service_worker.
    • supports background.scripts (or background.page) if service_worker is not specified.

To illustrate, this is an example of a cross-browser extension that supports scripts and service_worker. The example has this manifest.json file:

json
{
  "name": "Demo of service worker + event page",
  "version": "1",
  "manifest_version": 3,
  "background": {
    "scripts": ["background.js"],
    "service_worker": "background.js"
  }
}

And, background.js contains:

javascript
if (typeof browser == "undefined") {
  // Chrome does not support the browser namespace yet.
  globalThis.browser = chrome;
}
browser.runtime.onInstalled.addListener(() => {
  browser.tabs.create({ url: "http://example.com/first-run.html" });
});

When the extension is executed, this happens:

  • in Chrome, the service_worker property is used, and a service worker starts that opens the tab because, in a Manifest V3 extension, Chrome only supports service workers for background scripts.
  • in Firefox, the scripts property is used, and a script starts that opens the tab because Firefox only supports scripts for background scripts.
  • in Safari, the service_worker property is used, and a service worker starts that opens the tab because Safari gives priority to using service workers for background scripts.

Examples

json
  "background": {
    "scripts": ["jquery.js", "my-background.js"]
  }

Load two background scripts.

json
  "background": {
    "page": "my-background.html"
  }

Load a custom background page.

Browser compatibility

BCD tables only load in the browser