Manifest V3 migration guide
We have introduced a developer preview of Manifest V3 to Firefox. This page provides you with details of what's changed and how you adapt your extensions to take advantage of this preview.
We have introduced a developer preview of Manifest V3 to Firefox. This page provides you with details of what's changed and how you adapt your extensions to take advantage of this preview.
Manifest v3 (MV3) is the umbrella term for a number of foundational changes to the WebExtensions API in Firefox. The name refers to the declared manifest_version
key in each extension’s manifest.json file.
The Manifest v3 changes apply to extensions for Chromium-based browsers – such as Chrome, Edge, and Opera – Safari, and Firefox. While it is the goal to maintain a high degree of compatibility between the Firefox, Safari, and Chromium extension platforms, our implementation diverges where we think it matters and where our values point to a different direction.
This article discusses the overall changes introduced with the developer preview of Manifest v3 for Firefox and also highlights where it diverges from the Chrome and Safari implementation.
The developer preview of Manifest V3 is available in Firefox 101. However, to test your extensions you need to turn on the MV3 features. To do this, go to about:config
and:
extensions.manifestV3.enabled
to true
.xpinstall.signatures.required
to false
.You can now install MV3 extensions from about:debugging
.
If you want to permanently install an MV3 extension, you need to use the Nightly or Developer edition channels with xpinstall.signatures.required
set to false
.
Use web-ext run
with the --firefox-preview
option to quickly try your MV3 extension.
This section details the Manifest V3 changes made to Firefox and available in the developer preview.
The manifest.json key manifest_version
accepts 3
. To use Manifest V3, update your manifest.json file like this:
"manifest_version": 3
Search extensions must use local icons. This change prevents the unnecessary network pings that result from accessing remote icons.
To accommodate this change, provide a local icon and defined in your manifest.json chrome_settings_overrides manifest key like this:
"chrome_settings_overrides": {
"search_provider": {
"name": "Search engine",
"search_url": "https://www.searchengine.com/search/?q={searchTerms}",
"keyword": "search",
"favicon_url": "/imager/favicon.ico"
}
}
Host permissions are no longer defined in the manifest.json keys permissions
or optional_permissions
, rather, they are defined in the host_permissions
key.
Move all host permission specifications to the manifest.json key host_permissions
like this:
"permissions": [
"tabs",
"notifications"
],
"optional_permissions": [
"geolocation"
],
"host_permissions": [
"http://www.mysite.com/",
"*://*.example.org/*"
]
The features available under the manifest.json key browser_action
and the browserAction
API have moved to a new action
key and API. Also, the _execute_action
special shortcut is introduced.
As the old and new key and API are otherwise identical, the change is needed, are relatively straightforward, and are as follows:
"action": {
"browser_style": true,
"default_icon": {
"16": "button/geo-16.png",
"32": "button/geo-32.png"
},
"default_title": "Whereami?",
"default_popup": "popup/geo.html",
"theme_icons": [{
"light": "icons/geo-16-light.png",
"dark": "icons/geo-16.png",
"size": 16
}, {
"light": "icons/geo-32-light.png",
"dark": "icons/geo-32.png",
"size": 32
}]
}
browser.browserAction
to browser.action
._execute_browser_action
to _execute_action
in the commands
manifest key and in the menu.create
and menu.update
API methods (or their aliases contextMenus.create
and contextMenus.update
).In Chromium and Safari, the Browser Action and Page Action APIs are unified into the Action API, page_action
is merged into the renamed action
key, and the _execute_page_action
special shortcut is replaced by _execute_action
. Firefox retains the page action API, key, and special shortcut in the developer preview but will merge the page action features into action in a later release.
The new Scripting API takes over the features of tabs.insertCSS()
, tabs.removeCSS()
, and tabs.executeScript()
and adds capabilities to register, update, and unregister content scripts at runtime.
Also, the code
parameter is removed so that arbitrary strings can no longer be executed. This API requires the scripting
permission. So, you need to move any arbitrary strings executed as scripts to files and rewrite your code to use the Scripting API.
Firefox has extended its support for background scripts by enabling non-persistent background pages for Manifest V2 and V3. Using non-persistent background scripts greatly reduces your extension use of browser resources. However, MV3 removes support for persistent background pages.
If you want to migrate your MV2 extension to using non-persistent background pages, you can test them in the MV3 developer preview by enabling the preference extensions.eventPages.enabled
.
To migrate your extension to using non-persistent background pages you need to:
background
key to remove the "persistent"
property or set it to false
.extension.getBackgroundPage
to call a function from the background page, to runtime.getBackgroundPage
.menus.create
in a runtime.onInstalled
listener.More information on the migration process can be found on the background script page on MDN.
Safari also supports event-driven background scripts, however, Chromium has adopted service workers instead.
Content security policy (CSP) in the manifest.json key is changing to use the extension_pages
property. Manifest V3 has a more restrictive content security policy than Manifest V2, this may require further changes in your pages.
Move the extension’s CSP to the the manifest.json key to extension_pages
, like this:
"content_security_policy": {
"extension_pages": "default-src 'self'"
}
Web accessible resources are available only to the sites and extensions specified in the manifest. The developer preview supports resources
and matches
, but does not support the extension_ids
and use_dynamic_url
properties.
To migrate your extension, rewrite the manifest.json key ‘web_accessible_resources’ to specify the sites and extensions that can access the resources.
Chromium introduces promise support to many methods with the goal of eventually supporting promises on all appropriate methods. This will provide for greater compatibility between Firefox and Chrome extensions, given that Firefox already supports promises when using the browser.*
namespace.
In Manifest v2, Firefox extensions support the use of the chrome.*
namespace with APIs that provide asynchronous event handling using callbacks. In full release of Manifest v3, Firefox will support promises for asynchronous events in the chrome.*
namespace.
The format of the top-level manifest.json version
key in Firefox has evolved and became simpler: letters and other previously allowed symbols are no longer accepted. The value must be a string with 1 to 4 numbers separated with dots (e.g. 1.2.3.4
). Each number can have up to 9 digits and leading zeros before another digit are not allowed (e.g. 2.01
is forbidden but 0.2
, 2.0.1
and 2.1
are allowed).
manifest_version
to 3
.chrome_settings_overrides.search_provider.favicon_url
.permissions
and optional_permissions
and add them to the host_permissions
key.browser_action
to action
and update any API references from browser.browserAction
to browser.action
.content_security_policy.extension_pages
and update the CSP to conform to Manifest V3 requirements.applications
to browser_specific_settings
.browser_specific_settings.gecko.id
.version
is a string consisting of numbers separated with up to 3 dots. For details, see version format.We are working towards a general availability release of manifest V3 for a future release.
Develop
Develop
Develop