Update your code
Updates that are unrelated to other issues
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 cover replacing blocking web requests and improving security.
Replace tabs.executeScript() with scripting.executeScript()
In Manifest V3, executeScript()
moves from the tabs
API to the scripting
API. This requires changes to permissions in the manifest file in addition to actual code changes.
For the executeScript()
method you need:
- The
"scripting"
permission. - Either host permissions or the
"activeTab"
permission.
The scripting.executeScript()
method is similar to how it worked with tabs.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.
Manifest V2
async function getCurrentTab() {/* ... */}
let tab = await getCurrentTab();
chrome.tabs.executeScript(
tab.id,
{
file: 'content-script.js'
}
);
Manifest V3
async function getCurrentTab()
let tab = await getCurrentTab();
chrome.scripting.executeScript({
target: {tabId: tab.id},
files: ['content-script.js']
});
Replace tabs.insertCSS() and tabs.removeCSS() with scripting.insertCSS() and scripting.removeCSS()
In Manifest V3, insertCSS()
and removeCSS()
move from the tabs
API to the scripting
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 the scripting
API are similar to the functions on tabs
. 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 for insertCSS()
. The procedure for removeCSS()
is the same.
Manifest V2
chrome.tabs.insertCSS(tabId, injectDetails, () => {
// callback code
});
Manifest V3
const insertPromise = await chrome.scripting.insertCSS({
files: ["style.css"],
target: { tabId: tab.id }
});
// Remaining code.
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 the Action API. This requires changes in your manifest.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, the action
API does not provide hide()
and show()
as pageAction
did. If you still need page actions, you can either emulate them using declarative content or call enable()
or disable()
with a tab ID.
Replace "browser_action" and "page_action" with "action"
In the manifest.json
replace the "browser_action"
and "page_action"
fields with the "action"
field. Consult the reference for information on the "action"
field.
Manifest V2
{
...
"page_action": { ... },
"browser_action": {
"default_popup": "popup.html"
}
...
}
Manifest V3
{
...
"action": {
"default_popup": "popup.html"
}
...
}
Replace the browserAction and pageAction APIs with the action API
Where your Manifest V2 used the browserAction
and pageAction
APIs, you should now use the action
API.
Manifest V2
chrome.browserAction.onClicked.addListener(tab => { ... });
chrome.pageAction.onClicked.addListener(tab => { ... });
Manifest V3
chrome.action.onClicked.addListener(tab => { ... });
Replace functions that expect a Manifest V2 background context
Other extension contexts can only interact with extension service workers using message 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 that entails using sendMessage()
and implementing chrome.runtime.onMessage
in your extension service worker. Long term, you should plan to replace these calls with postMessage()
and a service worker's message 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.extension.connect() |
chrome.extension.getExtensionTabs() | chrome.extension.getViews() |
chrome.extension.getURL() | chrome.runtime.getURL() |
chrome.extension.lastError | Where methods return promises, use promise.catch() |
chrome.extension.onConnect | chrome.runtime.onConnect |
chrome.extension.onMessage | chrome.runtime.onMessage |
chrome.extension.onRequest | chrome.runtime.onRequest |
chrome.extension.onRequestExternal | chrome.runtime.onMessageExternal |
chrome.extension.sendMessage() | chrome.runtime.sendMessage() |
chrome.extension.sendRequest() | chrome.runtime.sendMessage() |
chrome.runtime.onSuspend (background scripts) | Not supported in extension service workers. Use the beforeunload 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 |