Chrome extension manifest v2 migration to v3

In 2023, Google would not allow Chrome extensions with manifest version before v3 to be listed on Chrome web stores as v3 extensions add more security privacy related restrictions on some of the functions. Hence all extensions with manifest v2 must migrate to v3. In this post, we would show how we did the migration for one of our extensions and the changes made.

There is a checklist provided by Chrome team on what needs to be updated so that the extension can still work in v3. It can be checked before your migration starts.

The first change needs to be made is to update the manifest_version from manifest.json. It needs to be updated from 2 to 3.

// v2
"manifest_version": 2,

// v3
"manifest_version": 3,

Next, the permissions section may need to be updated to separate normal permissions with host_permissions where some hosts are specified so that they can be accessed from the extension.

// v2
"permissions": [
  "contextMenus", 
  "declarativeContent",
  "notifications",
  "storage",
  "tabs",
  "*://www.pxlet.com/*"
],

// v3
"permissions": [
  "contextMenus", 
  "declarativeContent",
  "notifications",
  "storage",
  "tabs"
],
"host_permissions": [
  "*://www.pxlet.com/*"
],

Another big change is the background script now is changed to service_worker for more security restrictions.

// v2
"background": {
  "scripts": ["background.js"],
  "persistent": false
},

// v3
"background": {
  "service_worker": "background.js"
},

page_action is now replaced with action.

// v2
"page_action": {
  "default_popup": "popup.html",
  "default_icon": {
    "16": "image/logo.png",
    "32": "image/logo.png",
    "64": "image/logo.png",
    "128": "image/logo.png"
  }
}

// v3
"action": {
  "default_popup": "popup.html",
  "default_icon": {
    "16": "image/logo.png",
    "32": "image/logo.png",
    "64": "image/logo.png",
    "128": "image/logo.png"
  }
}

Post manifest.json update, there might be other changes needed in background script since some components are not available in service_worker.

XMLHttpRequest is not defined

In service_worker, the previous supported XMLHttpRequest is not defined now, to make async request, fetch() should be used.

// v2
let xhr = new XMLHttpRequest();
xhr.open("POST", "https://www.pxlet.com/lib/api/post.php", true);
xhr.onreadystatechange = function() {
    if (xhr.readyState === 4 && xhr.status == 200) {
        // ...
    } else {
        console.log(xhr.readyState);
        console.log(xhr.status);
    }
};
xhr.setRequestHeader("Content-type", "application/x-www-form-urlencoded");
let data = "somedata";
xhr.send(data);

// v3
let data = "somedata";

fetch("https://www.pxlet.com/lib/api/post.php", {
    method: "POST",
    headers: {
        "Content-type": "application/x-www-form-urlencoded"
    },
    mode: 'cors',
    credentials : 'include',
    body: data,
}).then((response) => {
    response.text().then((data) => {
        // ...
    });
}).catch((error) => {
    console.log(error);
})

window object is not defined

When opening anew tab, can use window.open() previously, with v3, this will not work anymore, instead one should use chrome.tabs.create().

// v2
window.open(link, '_blank');

// v3
chrome.tabs.create({ url: link });

notification not working

If no notification shows up in some cases where notifications are created, it might not be related to v3 migration, it might be there are some permissions are not open. For Windows, it might be that Google Chrome is not allowed to display notifications. It can be enabled in notification settings.

With all changes made, can load the unpacked package in Chrome and it should be loaded properly, otherwise there would be errors shown and can debug from there.

So far these are all the changes we have made based on the extension we have. There might be other changes needed for more complicated extensions. For those, can further check the official checklist for v3 migration or checking the errors when loading the updated extension in local environment.