Chrome Extension – Migrating from Manifest V2 to V3

Chrome extensions has been using manifest version 2 for a very long time. Google recently announced that they are phasing out version 2 and introducing version 3. This new version represents one of the biggest shift in the extensions since its inception in 2010. There has been a variety of new features introduced in manifest version 3 and extensions using this will enjoy security, privacy and performance enhancements.

Manifest V3 is a great means of improving your operational capacity on the extensions, along with boosting privacy and security. But, that is not all; there are many other changes that Manifest Version 3 brings to the table.

Here are some of them:

1. Service workers replace background pages.
2. Network request modification is now handled with the new declarativeNetRequest API.
3. Remotely-hosted code is no longer allowed; an extension can only execute JavaScript that is included within its package.
4. Promise support has been added to many methods, though callbacks are still supported as an alternative. (We will eventually support promises on all appropriate methods.)
5. A number of other, relatively minor feature changes are also introduced in Manifest V3.

If you are an extension owner, then it’s important that you immediately update your source code to meet the requirements of Manifest V3. This is sometimes easier said than done. So, here is a quick checklist for you to go through to ensure that you have truly migrated to Manifest V3.

 

How to migrate to Manifest v3?

Updating manifest.json file

To use the features of Manifest V3, you need to first update your manifest file. Naturally, you’ll change the manifest version to “3”, but there are a number of other things you need to change in the manifest file: host permissions, content security policy, action declarations, and web-accessible resources.

Manifest version

This change will determine whether you are using the Manifest V2 or Manifest V3 features. Change the value of manifest_version to 3 in the manifest.json file:

 

API Checklist

There are some changes you may need to make based on changes to the API surface. This section lists these changes.

Do you have host permissions in your manifest?

• Host permissions in Manifest V3 are a separate element; you don’t specify them in permissions or optional_permissions.
• Move host permissions into the host_permissions field in manifest.json.

Are you using background pages?

• Background pages are replaced by service workers in Manifest V3.
• Replace background.page or background.scripts with background.service_worker in manifest.json. Note that the service_worker field takes a string, not an array of strings.
• Remove background.persistent from manifest.json.
• Update background scripts to adapt to the service worker execution context.

Are you using the browser_action or page_action property in manifest.json?

• These properties are unified into a single property in Manifest V3.
• Replace these properties with action.

Are you using the chrome.browserAction or chrome.pageAction JavaScript API?

• These two equivalent APIs are unified into a single API in Manifest V3.
• Migrate to the chrome.action API.

Are you currently using the blocking version of chrome.webRequest?

• This API is replaced by declarativeNetRequest in Manifest V3.
• Migrate request modification logic to chrome.declarativeNetRequest rules.
• Replace the webRequestBlocking permission with declarativeNetRequest.
• Remove the webRequest permission if you no longer need to observe network requests.
• Remove unnecessary host permissions; blocking a request or upgrading a request’s protocol doesn’t require host permissions with declarativeNetRequest.

Are you executing remote code or arbitrary strings?

• You can no longer execute external logic using chrome.scripting.executeScript({code: ‘…’}), eval(), and new Function().
• Move all external code (JS, Wasm, CSS) into your extension bundle.
• Update script and style references to load resources from the extension bundle.
• Use chrome.runtime.getURL() to build resource URLs at runtime.

Are you executing functions that expect an Manifest V2 background context?

• The adoption of service workers in Manifest V3 isn’t compatible with methods like chrome.runtime.getBackgroundPage(), chrome.extension.getBackgroundPage(), chrome.extension.getExtensionTabs(), and chrome.extension.getViews().
• Migrate to a design that passes messages between other contexts and the background service worker.

Security Checklist

There are some changes you may need to make based on changes in security policy.

• Are you making CORS requests in content scripts? Move these requests to the background service worker.
• Are you using a custom content_security_policy in manifest.json? Replace content_security_policy with content_security_policy.extension_pages or content_security_policy.sandbox as appropriate.
• Remove references to external domains in script-src, worker-src, object-src, and style-src directives if present.