Architectural Changes in Chromium's Manifest V3 Transition

This article provides an overview of the core architectural changes introduced by the Chromium project during the transition of browser extensions from Manifest V2 to Manifest V3. Key updates include the replacement of persistent background pages with ephemeral service workers, the shift from dynamic network request interception to the declarativeNetRequest API, strict prohibitions on remotely hosted code, and modernized API structures. These fundamental shifts were designed to improve browser security, privacy, and performance, requiring developers to completely restructure how extensions process data and interact with the browser.

Service Workers Replace Background Pages

The most significant architectural shift in Manifest V3 is the removal of background pages in favor of extension service workers. In Manifest V2, extensions utilized persistent background pages—hidden HTML pages that ran continuously in the background, consuming system memory even when idle, and maintaining full access to the Document Object Model (DOM).

Manifest V3 replaces these with event-driven service workers. Service workers are ephemeral; they spin up only when a specific browser event triggers them and terminate immediately once their task is complete. Because service workers cannot hold global variables reliably across sessions, developers must now use the chrome.storage API to persist state. Additionally, service workers operate outside the standard document context and lack access to the DOM and the window object. To address use cases that strictly require DOM access—such as parsing HTML or interacting with the clipboard—Chromium introduced the chrome.offscreen API, which allows extensions to create minimal, hidden documents for specific, justified tasks.

Declarative Network Request Modification

Manifest V3 fundamentally alters how extensions interact with network traffic, a change that heavily impacts ad blockers and privacy extensions. Under Manifest V2, extensions used the blocking version of the chrome.webRequest API. This allowed the extension to intercept a network request in real-time, pause the browser's network stack, evaluate the request using custom JavaScript, and then decide whether to allow, block, or redirect it. This approach posed a privacy risk, as it required extensions to have read access to potentially sensitive user network data, and it created a performance bottleneck.

In Manifest V3, the blocking capabilities of webRequest are replaced by the chrome.declarativeNetRequest API. Instead of the extension intercepting every request, the extension now supplies the Chromium browser with a predefined set of rules. The browser itself evaluates network traffic against these rules natively and performs the blocking or modification. This architecture prevents the extension from reading the underlying network data, enhancing user privacy, and eliminates the performance overhead of waking up an extension script for every network request.

Prohibition of Remotely Hosted Code

To close a major security vulnerability, Manifest V3 strictly forbids the execution of remotely hosted code. In Manifest V2, extensions could fetch JavaScript files from external servers at runtime and execute them, or use functions like eval() to run dynamically generated strings of code. Bad actors frequently exploited this by submitting benign extensions to the web store and later serving malicious code from an external server after the extension was approved.

Manifest V3 requires all executable code to be bundled directly within the extension package at the time of submission. The browser's Content Security Policy (CSP) now blocks the execution of external scripts and disables eval() and new Function(). If an extension needs to update its logic, the developer must submit a new version of the entire extension package for review. Configuration data and rulesets can still be fetched remotely, provided they are processed strictly as data and not executable code.

Native Promise Support and API Unification

Manifest V3 modernizes the Chromium extension codebase by introducing native support for JavaScript Promises across most chrome.* APIs. In Manifest V2, asynchronous operations relied almost exclusively on callback functions, which often led to deeply nested, hard-to-maintain code. In Manifest V3, if a callback is not provided to an asynchronous API method, it automatically returns a Promise, allowing developers to use modern async/await syntax natively without third-party wrapper libraries.

Additionally, Manifest V3 simplifies the extension toolbar interface by unifying older APIs. In Manifest V2, developers had to choose between browser_action (for toolbar icons active on all pages) and page_action (for icons active only on specific pages). Manifest V3 merges these into a single chrome.action API, streamlining how extensions manage their toolbar presence.

Granular Host Permissions

The structure of the manifest.json file was updated to separate host permissions from general API permissions. In Manifest V2, both API access (like tabs or storage) and website access (like *://*.example.com/*) were grouped together under the permissions array.

Manifest V3 moves website access declarations to a dedicated host_permissions array. This structural change supports a broader architectural shift toward user-controlled security. Instead of granting an extension access to all requested websites permanently upon installation, the Manifest V3 architecture allows users to withhold host permissions by default and grant the extension access on a per-site or per-click basis at runtime.