Manifest V3 migration checklist
Published on • Updated on
This page provides a quick reference to help you identify any changes you might need to make to an Manifest V2 extension so that it works under Manifest V3. For more description of the nature of these changes see the Manifest V3 migration guide.
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
orbackground.scripts
withbackground.service_worker
in manifest.json. Note that theservice_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.
Service workers must be registered at root level: they cannot be in a nested directory.
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.
This only applies to user-installed extensions; force installed extensions (extensions distributed using ExtensionInstallForcelist). These extensions — typically used in an enterprise setting — can still use the blocking version of chrome.webRequest
.
- Migrate request modification logic to
chrome.declarativeNetRequest
rules. - Replace the
webRequestBlocking
permission withdeclarativeNetRequest
. - 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 using these scripting/CSS methods in the chrome.tabs API?
In Manifest V3, several methods move from chrome.tabs
to the chrome.scripting
API.
- Change any of the following Manifest V2 calls to use the correct Manifest V3 API:
Manifest V2 | Manifest V3 |
---|---|
tabs.executeScript() | scripting.executeScript() |
tabs.insertCSS() | scripting.insertCSS() |
tabs.removeCSS() | scripting.removeCSS() |
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. This section lists these changes.
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
withcontent_security_policy.extension_pages
orcontent_security_policy.sandbox
as appropriate. - Remove references to external domains in
script-src
,worker-src
,object-src
, andstyle-src
directives if present.
Last updated: Improve article