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):

The background key can also contain this optional property:

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.scripts (or background.page) and background.service_worker.

  • when both are specified, Safari uses background.scripts (or background.page) unless preferred_environment is set to service_worker.

  • when preferred_environment is set to service_worker and background.service_worker isn’t specified, Safari generates a service worker from background.scripts if present.

Cross-browser Manifest V3 background scripts

To support browsers with different Manifest V3 background script implementations, specify both scripts and service_worker in the background key. Browsers that support extension background service workers use service_worker, while browsers that use event pages for this case use scripts.

You do not need to include preferred_environment for this fallback behavior. Use preferred_environment only when you want Safari, or another browser that supports more than one background environment, to prefer service_worker where available.

This example shows the relevant parts of a manifest that includes both scripts and service_worker:

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

And, background.js contains:

browser.runtime.onInstalled.addListener(() => {
  browser.tabs.create({ url: "http://example.com/first-run.html" });
});

With this background configuration, this happens:

• in Chrome, the service_worker property is used, and a service worker starts because, in a Manifest V3 extension, Chrome only supports service workers for background scripts.

• in Firefox, the scripts property is used, and an event page starts because Firefox only supports scripts for background scripts.

• in Safari, the scripts property is used by default, and an event page starts.

Examples

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

Load two background scripts.

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

Load a custom background page.

Browser compatibility