Chrome Extension Migrate Manifest v3 from v2

A guide to converting Manifest V2 extensions to Manifest V3 extensions. Created by Exmo – a monetization platform for browser extensions.

In November 2020, Chrome unveiled Manifest V3, marking a significant transition from the long-standing Manifest V2 utilized by extensions. This transition carries substantial implications, particularly considering the array of new features introduced in V3. This tutorial will outline the necessary steps to migrate seamlessly from Manifest V2 to V3.

Note: Manifest V3 is typically supported in Chrome 88 or later versions. For extension features introduced in subsequent Chrome releases, please refer to the API reference documentation for compatibility details. If your extension relies on a particular API, you can define a minimum Chrome version requirement in the manifest file.

The format required for the manifest.json file varies slightly between Manifest V3 and Manifest V2. While this page focuses solely on changes specific to the manifest.json file, it’s important to note that several changes to scripts and pages will also necessitate adjustments to the manifest. These modifications are addressed alongside the migration tasks that require them.

Change the manifest version number

Change the value of the “manifest_version” field from 2 to 3.

Manifest V2

{
  ...
  "manifest_version": 2
  ...
}

Manifest V3

{
  ...
  "manifest_version": 3
  ...
}

Update host permissions

In Manifest V3, host permissions are now specified as a separate field and are not included within the “permissions” or “optional_permissions” sections.

Content scripts continue to be defined under “content_scripts.matches“. For further details, refer to the “Inject with static declarations” section.

Manifest V2

{
  ...
  "permissions": [
    "tabs",
    "bookmarks",
    "https://exmo.tech/",
  ],
  "optional_permissions": [
    "unlimitedStorage",
    "*://*/*",
  ]
  ...
}

Manifest V3

{
  ...
  "permissions": [
    "tabs",
    "bookmarks"
  ],
  "optional_permissions": [
    "unlimitedStorage"
  ],
  "host_permissions": [
    "https://exmo.tech/",
  ],
  "optional_host_permissions": [
    "*://*/*",
  ]
  ...
}

Update web accessible resources

The approach to handling web accessible resources has been updated in Manifest V3 to enhance security and limit exposure. Previously, in Manifest V2, the “web_accessible_resources” field allowed extensions to be detected by websites and potentially exploited by attackers if resources were exposed. This raised concerns related to fingerprinting or unintended resource access.

In Manifest V3, access to resources within extensions is restricted, and you now define permissions more selectively. Instead of simply listing files, you provide an array of objects, each mapping a set of resources to specific URLs or extension IDs.

For a clearer understanding, let’s compare the handling of web accessible resources between Manifest V2 and Manifest V3:

In Manifest V2:

• Specified resources were accessible to all websites by default.

In the Manifest V3 code snippet below:

• Resources are restricted to only be accessible to https://example.com.
• Certain images are made available to all websites.

For further details, refer to the documentation on Web accessible resources and Match patterns.

Manifest V2

{
  ...
  "web_accessible_resources": [
    "images/*",
    "style/extension.css",
    "script/extension.js"
  ],
  ...
}

Manifest V3

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

Continue reading:

• Migrate to a service worker
• Update your code
• Replace blocking web request listeners
• Improving Extension Security in Manifest V3

Frequently Asked Questions