How Firefox Implemented Manifest V3 Background Scripts

This article explores how Mozilla’s Firefox browser implemented Manifest V3 (MV3) background scripts by utilizing Event Pages alongside Service Workers. Unlike Chromium-based browsers, which strictly mandated ephemeral Service Workers for MV3, Firefox adopted a hybrid approach. By supporting Event Pages, Firefox allowed extension developers to retain persistent access to the Document Object Model (DOM) and familiar web APIs during execution, while simultaneously supporting Service Workers to ensure seamless cross-browser compatibility.

The Manifest V3 Background Shift

When Google introduced Manifest V3, the most controversial change was the removal of Manifest V2's persistent background pages in favor of Service Workers. Service Workers are event-driven scripts that run independently of web pages, terminating when not in use to save system memory. However, they lack access to the DOM, the window object, and several standard Web APIs.

Mozilla recognized that Service Workers were not originally designed for the needs of browser extensions. To prevent breaking existing extensions and to reduce the migration burden on developers, Firefox engineered its MV3 implementation to use Event Pages as its primary background script mechanism.

How Firefox Uses Event Pages

Event Pages operate as a middle ground between MV2's persistent background pages and MV3's Service Workers. Like Service Workers, Event Pages are lifecycle-driven: they load when an event is triggered (such as a user clicking an extension icon or a network request occurring) and unload after a period of inactivity.

However, unlike Service Workers, an Event Page runs within a hidden, standard browser document. While the Event Page is active, it provides a persistent execution environment that mirrors the traditional background pages of MV2.

This implementation provides several critical capabilities that Service Workers lack:

  • Full DOM Access: Extensions can natively parse HTML/XML, manipulate the DOM, use the <canvas> element, and interact with audio or video elements.
  • Global Scope Support: The standard window and document objects remain accessible.
  • Legacy API Compatibility: Developers can continue using XMLHttpRequest, localStorage, and long-lived WebSockets without having to rewrite their logic for the restrictive Service Worker environment.
  • Simplified State Management: While extensions still need to save state before the Event Page unloads, Firefox gives developers more leeway with execution timers compared to Chrome's aggressive Service Worker termination.

Coexistence with Service Workers

While Mozilla favored Event Pages, they also needed to ensure that extensions built specifically for Chrome would still function in Firefox. To achieve this, Firefox implemented support for both background.scripts (Event Pages) and background.service_worker (Service Workers) within the manifest.json file.

Developers can declare both properties in the same manifest to achieve cross-browser compatibility from a single codebase:

"background": {
  "scripts": ["background.js"],
  "service_worker": "background.js",
  "type": "module"
}

The Browser Fallback Mechanism

This dual-declaration works because of how different browser engines parse the manifest.json file:

  1. In Firefox: When Firefox parses the manifest and sees both properties, it prioritizes the scripts array. It spins up the hidden HTML document and runs background.js as an Event Page, granting it full DOM access. If an extension only declares service_worker, Firefox falls back to running the script in a Service Worker context.
  2. In Chromium Browsers: Chrome and Edge read the service_worker property and initialize the script as a Service Worker. They ignore the scripts array entirely, issuing only a harmless warning in the developer console that the property is unrecognized in their MV3 specification.

By implementing Event Pages alongside Service Workers, Firefox preserved the powerful capabilities of MV2 extensions while adopting the security and performance improvements of MV3, offering developers a pragmatic path forward for cross-browser extension development.