Update your code Stay organized with collections Save and categorize content based on your preferences.
Updates that are unrelated to other issues
Note: Manifest V3 is supported generally in Chrome 88 or later. For extension features added in later Chrome versions, see theAPI reference documentation for support information. If your extension requires a specific API, you can specifya minimum chrome version in the manifest file.This is the first of three sections describing changes needed for code that is not part of the extension service worker. This section is for required code changes that are unrelated to other issues. The next two sections coverreplacing blocking web requests andimproving security.
Replace tabs.executeScript() with scripting.executeScript()
In Manifest V3,executeScript()
moves from thetabs
API to thescripting
API. This requires changes to permissions in the manifest file in addition to actual code changes.
For theexecuteScript()
method you need:
- The
"scripting"
permission. - Either host permissions or the
"activeTab"
permission.
Thescripting.executeScript()
method is similar to how it worked withtabs.executeScript()
. There are a few differences.
- While the old method could only take a single file, the new method can take an array of files.
- You also pass a
ScriptInjection
object instead ofInjectDetails
. There are multiple differences between the two. For example, thetabId
is now passed as a member ofScriptInjection.target
instead of as a method argument.
The example shows how to do this.
asyncfunctiongetCurrentTab(){/* ... */}lettab=awaitgetCurrentTab();chrome.tabs.executeScript(tab.id,{file:'content-script.js'});
In a background script file.
asyncfunctiongetCurrentTab()lettab=awaitgetCurrentTab();chrome.scripting.executeScript({target:{tabId:tab.id},files:['content-script.js']});
In the extension service worker.
Replace tabs.insertCSS() and tabs.removeCSS() with scripting.insertCSS() and scripting.removeCSS()
In Manifest V3,insertCSS()
andremoveCSS()
move from thetabs
API to thescripting
API. This requires changes to permissions in the manifest file in addition to code changes:
- The
"scripting"
permission. - Either host permissions or the
"activeTab"
permission.
The functions on thescripting
API are similar to the functions ontabs
. There are a few differences.
- When calling these methods, you pass a
CSSInjection
object instead ofInjectDetails
. - The
tabId
is now passed as a member ofCSSInjection.target
instead of as a method argument.
The example shows how to do this forinsertCSS()
. The procedure forremoveCSS()
is the same.
chrome.tabs.insertCSS(tabId,injectDetails,()=>{// callback code});
In a background script file.
constinsertPromise=awaitchrome.scripting.insertCSS({files:["style.css"],target:{tabId:tab.id}});// Remaining code.
In the extension service worker.
Replace Browser Actions and Page Actions with Actions
Browser actions and page actions were separate concepts in Manifest V2. Though they started with distinct roles, the differences between them decreased over time. In Manifest V3, these concepts are consolidated into theAction API. This requires changes in yourmanifest.json
and extension code that is different from what you would have put in your Manifest V2 background script.
Actions in Manifest V3 most closely resemble browser actions; however, theaction
API does not providehide()
andshow()
aspageAction
did. If you still need page actions, you can eitheremulate them using declarative content or callenable()
ordisable()
with a tab ID.
Replace "browser_action" and "page_action" with "action"
In themanifest.json
replace the"browser_action"
and"page_action"
fields with the"action"
field. Consult the reference forinformation on the"action"
field.
{..."page_action":{...},"browser_action":{"default_popup":"popup.html"}...}
{..."action":{"default_popup":"popup.html"}...}
Replace the browserAction and pageAction APIs with the action API
Where your Manifest V2 used thebrowserAction
andpageAction
APIs, you should now use theaction
API.
chrome.browserAction.onClicked.addListener(tab=>{...});chrome.pageAction.onClicked.addListener(tab=>{...});
chrome.action.onClicked.addListener(tab=>{...});
Replace callbacks with promises
In Manifest V3, many extension API methods return promises. APromise is a proxy or placeholder for a value returned by an asynchronous method. If you've never used Promises, you canread about them on MDN. This page describes what you need to know to use them in a Chrome extension.
For backward compatibility, many methods continue to support callbacks after promise support is added. Be aware that you cannot use both on the same function call. If you pass a callback, the function will not return a promise and if you want a promise returned do not pass a callback. Some API features, such as event listeners, will continue to require callbacks. To check whether a method supports promises, look for the "Promise" label in its API reference.
To convert from a callback to a promise, remove the callback and handle the returned promise. The example below is taken from theoptional permissions sample,newtab.js
specifically. The callback version shows what the sample's call torequest()
would look like with a callback. Note that the promise version could be rewritten with async and await.
chrome.permissions.request(newPerms,(granted)=>{if(granted){console.log('granted');}else{console.log('not granted');}});
constnewPerms={permissions:['topSites']};chrome.permissions.request(newPerms).then((granted)=>{if(granted){console.log('granted');}else{console.log('not granted');}});
Replace functions that expect a Manifest V2 background context
Other extension contexts can only interact with extension service workers usingmessage passing. Consequently, you'll need to replace calls that expect a background context, specifically:
chrome.runtime.getBackgroundPage()
chrome.extension.getBackgroundPage()
chrome.extension.getExtensionTabs()
Your extension scripts should use message passing to communicate between a service worker and other parts of your extension. Currently this can be accomplished by usingsendMessage()
and implementingchrome.runtime.onMessage
in your extension service worker. Long term, you should plan to replace these calls withpostMessage()
and a service worker'smessage event handler.
Replace unsupported APIs
The methods and properties listed below need to change in Manifest V3.
Manifest V2 method or property | Replace with |
---|---|
chrome.extension.connect() | chrome.runtime.connect() |
chrome.extension.connectNative() | chrome.runtime.connectNative() |
chrome.extension.getExtensionTabs() | chrome.extension.getViews() |
chrome.extension.getURL() | chrome.runtime.getURL() |
chrome.extension.lastError | Where methods return promises, usepromise.catch() |
chrome.extension.onConnect | chrome.runtime.onConnect |
chrome.extension.onConnectExternal | chrome.runtime.onConnectExternal |
chrome.extension.onMessage | chrome.runtime.onMessage |
chrome.extension.onRequest | chrome.runtime.onMessage |
chrome.extension.onRequestExternal | chrome.runtime.onMessageExternal |
chrome.extension.sendMessage() | chrome.runtime.sendMessage() |
chrome.extension.sendNativeMessage() | chrome.runtime.sendNativeMessage() |
chrome.extension.sendRequest() | chrome.runtime.sendMessage() |
chrome.runtime.onSuspend (background scripts) | Not supported in extension service workers. Use thebeforeunload document event instead. |
chrome.tabs.getAllInWindow() | chrome.tabs.query() |
chrome.tabs.getSelected() | chrome.tabs.query() |
chrome.tabs.onActiveChanged | chrome.tabs.onActivated |
chrome.tabs.onHighlightChanged | chrome.tabs.onHighlighted |
chrome.tabs.onSelectionChanged | chrome.tabs.onActivated |
chrome.tabs.sendRequest() | chrome.runtime.sendMessage() |
chrome.tabs.Tab.selected | chrome.tabs.Tab.highlighted |
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2023-03-09 UTC.