Chrome Manifest V2 vs Manifest V3: What Changed for Extension Developers?

byMicMoza - 0 Comments

Manifest V3 changes four areas that matter most to Chrome extension developers: how background code runs, how network requests are modified, whether remote code can be executed, and how permissions are declared.

Manifest V2 has now reached the end of its lifecycle. Google removed the remaining Manifest V2

Chrome Manifest V2 vs Manifest V3 comparison showing changes for Chrome extension developers
Chrome Manifest V2 vs Manifest V3: principais mudanças que os desenvolvedores precisam conhecer ao atualizar extensões do Chrome.

extensions from the Chrome Web Store on August 31, 2026. This guide explains the main differences between Manifest V2 and Manifest V3, what developers need to change, and the recommended migration order.

If you are not a developer and only want to understand why a Chrome extension stopped working, read our guide on what happened to Chrome extensions after Manifest V2 was removed.

Manifest V2 vs Manifest V3 at a Glance

Area Manifest V2 Manifest V3
Background code Long-lived background page Service worker that runs when needed
Network requests Blocking webRequest declarativeNetRequest rules
Remote code Allowed in some circumstances Executable JavaScript must be included in the extension package
Host permissions Declared in permissions Declared separately in host_permissions
Web accessible resources List of files Objects containing resources and matches
Chrome Web Store No longer supported Current platform version

Where Manifest V2 Stands Today

Google phased out Manifest V2 over several years. The main milestones were:

  • January 2022: the Chrome Web Store stopped accepting new public and unlisted V2 extensions.
  • June 2022: new private V2 extensions were no longer accepted.
  • June 2024: warning messages began appearing in Chrome's extension management interface in pre-stable channels.
  • March 2025: V2 extensions were disabled by default for users, although they could still be temporarily re-enabled.
  • July 2025: Manifest V2 was disabled across Chrome, preventing users from re-enabling it.
  • August 31, 2026: remaining V2 extensions were removed from the Chrome Web Store.

For developers, the practical result is simple: maintaining a Chrome extension now means migrating it to Manifest V3.

Source: Manifest V2 support timeline, Chrome for Developers.

1. Background Pages Became Service Workers

One of the biggest changes is the replacement of persistent background pages with extension service workers.

In Manifest V2, a background page could remain active for long periods. In Manifest V3, the service worker starts when an event requires it and can be stopped when it becomes inactive.

This changes how extension developers should handle application state.

  • Global variables are not persistent. Values stored only in memory can disappear when the service worker stops.
  • localStorage is unavailable. Extension service workers should use chrome.storage or IndexedDB when persistent data is required.
  • Timers need a different approach. Chrome recommends using the Alarms API instead of relying on long-running timers.

For example, this approach can lose the counter when the service worker stops:

let clickCount = 0;

chrome.action.onClicked.addListener(() => {
  clickCount++;
});

A persistent approach stores the value using the extension storage API:

chrome.action.onClicked.addListener(async () => {
  const { clickCount = 0 } =
    await chrome.storage.local.get("clickCount");

  await chrome.storage.local.set({
    clickCount: clickCount + 1
  });
});

Developers should also register event listeners synchronously so Chrome can correctly wake the service worker when an event occurs.

Source: Chrome extension service worker lifecycle.

2. Blocking webRequest Gave Way to declarativeNetRequest

Manifest V2 allowed extensions to use blocking webRequest listeners to cancel, redirect, or modify network requests while they were being processed.

Manifest V3 changes this model by using the declarativeNetRequest API for many request-filtering tasks. Instead of running custom code for every request, developers define rules that Chrome can apply directly.

A simple blocking rule can look like this:

[
  {
    "id": 1,
    "priority": 1,
    "action": {
      "type": "block"
    },
    "condition": {
      "urlFilter": "||example.com",
      "resourceTypes": ["main_frame"]
    }
  }
]

Redirects can use the redirect action, while some header changes can be handled through modifyHeaders.

This is particularly important for extensions that filter advertisements, block trackers, redirect URLs, or modify network traffic. Developers should review each feature individually rather than attempting a simple line-by-line conversion from V2 to V3.

Source: Replace blocking web request listeners.

3. Remotely Hosted Code Is No Longer Allowed

Manifest V3 requires executable JavaScript to be included in the extension package. An extension should not download executable code from a remote server and then execute it.

This affects extensions that previously loaded JavaScript from a CDN or another external server.

Developers may still communicate with remote servers and retrieve data. For example, an extension can retrieve account information, configuration data, images, or other resources when those resources are not being used to execute remote logic.

The important distinction is that the extension's functionality must be contained in the reviewed extension package rather than being supplied as executable code from a remote location.

Sources: Chrome Web Store Manifest V3 requirements and Handling remote hosted code.

4. Permissions and Manifest Fields Changed

The migration starts with the extension's manifest.json file.

  1. Change "manifest_version" from 2 to 3.
  2. Move host match patterns from permissions to host_permissions when required.
  3. Move optional host permissions to optional_host_permissions.
  4. Update web_accessible_resources to the Manifest V3 format.

For example, Manifest V3 uses objects to define which resources can be accessed and by which matching sites:

"web_accessible_resources": [
  {
    "resources": ["images/*"],
    "matches": ["*://*/*"]
  },
  {
    "resources": ["style/extension.css"],
    "matches": ["https://example.com/*"]
  }
]

Content script match patterns remain under content_scripts.matches. Developers should review every permission rather than simply copying the old manifest into the new format.

Source: Update the extension manifest.

Manifest V2 to V3 Migration Checklist

A practical migration order is:

  1. Check the current version. Open manifest.json and confirm the value of manifest_version.
  2. Update the manifest. Change the structure and permissions required by V3.
  3. Convert background logic. Move persistent background code into a service worker.
  4. Move persistent state. Replace important global variables with chrome.storage or another appropriate storage mechanism.
  5. Replace blocking network logic. Evaluate whether declarativeNetRequest can handle each use case.
  6. Remove remote executable code. Include required JavaScript in the extension package.
  7. Test service worker behavior. Make sure the extension continues working after the worker becomes inactive and starts again.
  8. Review permissions. Remove permissions that are no longer necessary and verify the remaining ones.

Google provides a detailed Manifest V3 migration checklist for developers working through these changes.

Common Migration Mistakes

  • Keeping important data only in memory. Service workers can stop, causing global variables to disappear.
  • Trying to keep the service worker alive. The V3 architecture is designed around event-driven execution.
  • Converting webRequest code line by line. Network functionality should be redesigned around the available declarative rules.
  • Registering event listeners too late. Event listeners should be registered synchronously so Chrome can properly wake the service worker.
  • Leaving unnecessary permissions in the manifest. Review permissions during migration instead of carrying every V2 permission forward.

Related Browser and Software Guides

If you are troubleshooting a browser or extension problem rather than developing an extension, these related guides may also help:

Frequently Asked Questions

Can I still publish a Manifest V2 extension?

No. Manifest V2 is no longer accepted as the current Chrome extension platform, and the remaining V2 listings were removed from the Chrome Web Store on August 31, 2026.

Do I have to rewrite my extension from scratch?

Not necessarily. The amount of work depends on how the extension uses background pages, network requests, remote code, permissions, and other V2 features. Many extensions can be migrated by updating specific parts of the existing codebase.

Is webRequest completely removed in Manifest V3?

No. The important change concerns blocking request interception. Extensions can still use webRequest for supported non-blocking use cases, while declarativeNetRequest is used for many request modification and filtering tasks.

Why does my state keep resetting in Manifest V3?

Chrome can stop an inactive extension service worker. Data stored only in global variables is therefore not guaranteed to survive. Persistent information should be stored using an appropriate storage mechanism such as chrome.storage.

Conclusion

Manifest V3 changes the architecture of Chrome extensions rather than simply changing the value of manifest_version. Developers need to adapt background code to service workers, move persistent state into storage, replace applicable blocking network logic with declarative rules, remove remotely hosted executable code, and review permissions.

With Manifest V2 no longer available as the current Chrome extension platform, developers maintaining older extensions should treat migration as a necessary upgrade rather than an optional change. The safest approach is to work through each affected area systematically and test the extension after every major change.

MicMoza

Post a Comment

Post a Comment