From MV2 to MV3: A Practical Migration Field Guide for Chrome Extensions

Chrome's Manifest V2 to V3 migration deadline has passed, but plenty of extensions are still running legacy code. Here's how to migrate without breaking everything.

The Core Changes

MV3 makes three big changes:

1. Background pages → Service Workers (biggest impact)
2. host_permissions → optional_host_permissions (security model change)
3. Blocking webRequest → declarativeNetRequest (network blocking API)

Migration Step by Step

Convert Background to Service Worker

// MV2 background.js
chrome.runtime.onMessage.addListener((request) => {
  console.log(request);
});

// MV3 service-worker.js  
chrome.runtime.onMessage.addListener((request) => {
  console.log(request);
});

Update Manifest

{
  "manifest_version": 3,
  "background": {
    "service_worker": "service-worker.js"
  }
}

The Pain Points

• Timers: setTimeout doesn't work in service workers. Use chrome.alarms instead.
• State persistence: Service workers are ephemeral. Any state must be re-read from storage.
• WebRequest blocking: Migrate to declarativeNetRequest.

Tooling Help

The ExtensionBooster MV2→MV3 converter automates the simpler migrations and flags the parts that need manual attention. They also offer free tools for extension developers at every stage of the migration.