What Is Manifest V3: Architecture, Rules, and Differences Explained

Manifest V3 is the modern specification for browser extensions that replaces long-running background pages with ephemeral service workers, restricts remotely hosted scripts, and substitutes blocking network interception with declarative rule engines. Announced by Google in 2020 to redefine browser security, performance, and user privacy, it serves as the required extension blueprint for Chromium-based platforms while introducing new constraints for background execution and network filtering.

Every browser extension requires a configuration file named manifest.json, which acts as an architectural blueprint that informs the browser of its name, version, declared capabilities, and required permissions. Manifest V2 served as the ecosystem baseline starting in 2012, but Manifest V3 introduces substantial architectural shifts that alter how background processes maintain state, how network requests are modified, and how external scripts are executed.

Manifest V2 vs. Manifest V3 Technical Specifications

To understand how Manifest V3 fundamentally reorders extension architecture, compare the technical mechanics and constraints of both specifications:

How Manifest V3 System Changes Function

The architectural rules in the reference table change how developers design extensions across three foundational layers: process management, network security, and asset scoping.

1. Ephemeral Background Execution via Service Workers

In Manifest V2, background scripts ran inside persistent background pages that lived continuously in the background, retaining global variables in memory for as long as the browser remained open. Manifest V3 eliminates background pages in favor of extension service workers. These workers are strictly event-driven: they boot up to handle an incoming notification, web message, or system trigger, and terminate after an idle interval (typically 10 to 30 seconds).

Because service workers shut down frequently, developers cannot rely on in-memory global state such as standard JavaScript maps, sets, or simple variables. Any state meant to survive lifecycle teardowns must be persisted to local storage. Furthermore, service workers run entirely outside of a visual document tree, meaning they have no direct access to window, document, or DOM manipulation APIs. For workloads requiring an actual document context—such as accessing the clipboard or executing computationally demanding background tasks—Manifest V3 provides dedicated offscreen documents via chrome.offscreen.

2. Network Filtering via Declarative Rules

Under Manifest V2, content blockers and privacy tools relied heavily on the blocking version of the webRequest API. This required the browser to pause every outgoing network call, serialize the request payload, pass it into the extension’s background process, and await an asynchronous response on whether to allow, redirect, or block the packet. This model introduced performance overhead and allowed extensions to inspect sensitive personal data.

Manifest V3 deprecates the blocking webRequest mechanism in favor of declarativeNetRequest. Instead of intercepting network packets at runtime, the extension pre-registers a collection of static or dynamic declarative rules directly with the browser. The browser’s native engine checks incoming and outgoing requests against those rules and applies blocks or modifications internally, removing the performance penalty and preventing the extension from directly inspecting raw network streams.

3. Package Containment and Scoped Resources

Under Manifest V2, extensions could fetch scripts from external content delivery networks or private servers at runtime. Manifest V3 blocks all remotely hosted code. Every line of executable JavaScript must be packaged inside the .zip archive distributed through the extension registry, ensuring that store review teams can evaluate the full source code for malicious behavior prior to publication.

Similarly, Manifest V3 restructures web accessible resources. In V2, making an icon or stylesheet accessible to a web page required listing a path pattern in an open array. This allowed malicious third-party websites to fingerprint installed extensions by attempting to load known asset URLs. Manifest V3 enforces granular scoping: developers must define both the resource paths and the explicit domains permitted to request them.

Migrating an Extension Context to Manifest V3

To see how these rules apply, examine a complete migration of a user metrics extension from Manifest V2 to Manifest V3.

Step 1: Updating the Manifest Blueprint

In Manifest V2, background scripts and web-accessible resources were defined loosely:

{
 "manifest_version": 2,
 "name": "Analytics Reader",
 "version": "1.0.0",
 "background": {
 "scripts": ["background-analytics.js"],
 "persistent": true
 },
 "permissions": [
 "storage",
 "https://telemetry.example.org/*"
 ],
 "web_accessible_resources": [
 "assets/badge.png"
 ]
}

In Manifest V3, the schema shifts to a service worker, moves external endpoints out of the host permissions array (as Chrome V3 allows standard outbound API requests without explicit host permissions for fetching), and scopes web accessible resources:

{
 "manifest_version": 3,
 "name": "Analytics Reader",
 "version": "2.0.0",
 "background": {
 "service_worker": "background-analytics.js"
 },
 "permissions": [
 "storage"
 ],
 "web_accessible_resources": [
 {
 "resources": ["assets/badge.png"],
 "matches": ["https://dashboard.example.org/*"]
 }
 ]
}

Step 2: Reworking State Handling in the Background Code

In Manifest V2, background state could remain safely in memory:

// Manifest V2 Background Script (Persistent)
let cachedSessionCounter = 0;

chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
 if (message.action === "incrementCounter") {
 cachedSessionCounter += 1;
 sendResponse({ currentCount: cachedSessionCounter });
 }
 return true;
});

Because Manifest V3 service workers shut down after 10 to 30 seconds of inactivity, cachedSessionCounter would reset back to 0 whenever the worker restarts. The script must be rewritten to leverage storage APIs and promise-based patterns:

// Manifest V3 Service Worker (Event-Driven)
chrome.runtime.onMessage.addListener((message, sender, sendResponse) => {
 if (message.action === "incrementCounter") {
 // Retrieve existing value from storage asynchronously
 chrome.storage.local.get({ sessionCounter: 0 }).then((data) => {
 const updatedCount = data.sessionCounter + 1;
 
 // Save state before the service worker goes idle
 return chrome.storage.local.set({ sessionCounter: updatedCount })
.then(() => {
 sendResponse({ currentCount: updatedCount });
 });
 });
 
 // Return true to keep message port open for asynchronous sendResponse
 return true;
 }
});

After refactoring your manifest and code structure, you can verify your configuration keys and permission boundaries with the Manifest V3 Permission Checker to ensure no deprecated V2 flags or excessive permissions remain.

Browser Support Exceptions and Deviations

While Manifest V3 is the mandated baseline for the Chrome Web Store, extension execution environments vary significantly depending on the browser and distribution pipeline.

Firefox Extension Support

Mozilla Firefox supports Manifest V3 while maintaining active support for Manifest V2 without immediate deprecation plans. Furthermore, Firefox handles network permissions differently: under Firefox with V2, outbound API endpoints require explicit inclusion in the permissions array, whereas Chrome V3 does not require host permissions simply to make outgoing fetch calls. Host permissions in Chrome V3 are reserved for injecting content scripts or reading cookies from specific domains.

Alternative Chromium Browsers (Brave)

Some Chromium-based browsers patch upstream code to retain older capabilities. For example, the Brave browser maintains native ad-blocking tools (Brave Shields) directly inside its core C++ codebase, completely independent of extension manifest versions. Because Shields do not rely on MV2 or MV3, changes to the extension platform do not impact their filtering efficiency. Furthermore, Brave maintains dedicated backend hosting for select privacy-centric Manifest V2 extensions—specifically AdGuard, NoScript, uBlock Origin, and uMatrix—allowing users to download and run them even after upstream Chrome Web Store deprecations.

Strict Content Blocking Limitations

For complex content blocking extensions, declarative rules impose caps on rule volume and restrict cosmetic filtering compared to the old blocking APIs. These constraints mean that Manifest V3 rulesets do not apply equally to every browser environment, and extensions targeting multiple browser engines often maintain platform-specific build configurations.