Docs4dev
Docs
web_extensions / latest / manifest.json.html

manifest.json

Note: This article describes manifest.json for web extensions. If you are looking for information about the manifest.json in PWAs, check out the Web App Manifest article.

The manifest.json file is the only file that every extension using WebExtension APIs must contain.

Using manifest.json, you specify basic metadata about your extension such as the name and version, and can also specify aspects of your extension's functionality (such as background scripts, content scripts, and browser actions).

It is a JSON-formatted file, with one exception: it is allowed to contain "//"-style comments.

List of manifest.json keys

These are the manifest.json keys; these keys are available in Manifest V2 and above unless otherwise noted:

Notes about manifest.json keys

  • "manifest_version", "version", and "name" are the only mandatory keys.
  • "default_locale" must be present if the "_locales" directory is present, and must be absent otherwise.
  • "browser_specific_settings" is not supported in Google Chrome.

Accessing manifest.json keys at runtime

You can access your extension's manifest from the extension's JavaScript using the runtime.getManifest() function:

browser.runtime.getManifest().version;

Example

The block below shows the basic syntax for some common manifest keys.

Note: This is not intended to be used as a copy-paste-ready example. Selecting the keys you'll need depends on the extension you are developing.

For complete example extensions, see Example extensions.

{
  "browser_specific_settings": {
    "gecko": {
      "id": "addon@example.com",
      "strict_min_version": "42.0"
    }
  },

  "background": {
    "scripts": ["jquery.js", "my-background.js"],
  },

  "browser_action": {
    "default_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default_title": "Whereami?",
    "default_popup": "popup/geo.html"
  },

  "commands": {
    "toggle-feature": {
      "suggested_key": {
        "default": "Ctrl+Shift+Y",
        "linux": "Ctrl+Shift+U"
      },
      "description": "Send a 'toggle-feature' event"
    }
  },

  "content_security_policy": "script-src 'self' https://example.com; object-src 'self'",

  "content_scripts": [
    {
      "exclude_matches": ["*://developer.mozilla.org/*"],
      "matches": ["*://*.mozilla.org/*"],
      "js": ["borderify.js"]
    }
  ],

  "default_locale": "en",

  "description": "…",

  "icons": {
    "48": "icon.png",
    "96": "icon@2x.png"
  },

  "manifest_version": 2,

  "name": "…",

  "page_action": {
    "default_icon": {
      "19": "button/geo-19.png",
      "38": "button/geo-38.png"
    },
    "default_title": "Whereami?",
    "default_popup": "popup/geo.html"
  },

  "permissions": ["webNavigation"],

  "version": "0.1",

  "user_scripts": {
    "api_script": "apiscript.js",
  },

  "web_accessible_resources": ["images/my-image.png"]
}

Browser compatibility

Desktop Mobile
Chrome Edge Firefox Internet Explorer Opera Safari WebView Android Chrome Android Firefox for Android Opera Android Safari on IOS Samsung Internet
action 88 88 109 ? 74 15.4 ? ? 109 ? 15.4 ?
author Yes
14This property is required.
52 ? Yes
14Not displayed in Safari Extensions settings.
? ? 52 ?
15Not displayed in Safari Extensions settings.
?
background Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
browser_action
Yes["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
14Available for use in Manifest V2 only.
48Available for use in Manifest V2 only.
?
Yes["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
14["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
? ?
55Available for use in Manifest V2 only.
?
15["Available for use in Manifest V2 only.", "If an extension defines a browser action, it is not allowed to define a page action as well."]
?
browser_specific_settings No 15–79
42Before Firefox 48, this property was required.
? No
14Supports strict_min_version and strict_max_version in a safari block.
? ?
42Before Firefox 48, this property was required.
?
15Supports strict_min_version and strict_max_version in a safari block.
?
chrome_settings_overrides Yes 79 55 ? No No ? ? No ? No ?
chrome_url_overrides Yes 79 54 ? No 1514.1 ? ? No ? 15 ?
commands Yes 79 48 ? Yes
14Changing the keyboard shortcut for a command is not supported.
? ? No ?
15Changing the keyboard shortcut for a command is not supported.
?
content_scripts
YesContent scripts are not applied to tabs already open when the extension is loaded.
14 48 ?
YesContent scripts are not applied to tabs already open when the extension is loaded.
14Content scripts are not applied to tabs until the user grants permission via the extension's access popover in the toolbar.
? ? 48 ?
15Content scripts are not applied to tabs until the user grants permission via the extension's access alert.
?
content_security_policy
YesUntil Chrome 110, the object-src directive was required with a secure source. From Chrome 111, the object-src directive is optional.
YesUntil Edge 110, the object-src directive was required with a secure source. From Edge 111, the object-src directive is optional.
48["Firefox does not support 'http://127.0.0.1' or 'http://localhost' as script sources: they must be served over HTTPS.", "Until Firefox 105, the object-src directive was required with a secure source. From Firefox 106, the object-src directive is optional."]
?
YesUntil Opera 96, the object-src directive was required with a secure source. From Opera 97, the object-src directive is optional.
14There is no requirement to include the object-src directive.
? ? No ?
15There is no requirement to include the object-src directive.
?
declarative_net_request 84 84 No ? 70 15 ? ? No ? 15 ?
default_locale Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
description Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
developer No No 52 ? Yes No ? ? 52 ? No ?
devtools_page Yes 79 54 ? Yes 16 ? ? No ? No ?
externally_connectable Yes 79
NoSee bug 1319168.
? Yes
15.4Safari only supports the matches property.
? ? No ?
15.4Safari only supports the matches property.
?
homepage_url Yes 79 48 ? Yes
14Not displayed in Safari Extensions settings.
? ? 48 ?
15Not displayed in Safari Extensions settings.
?
host_permissions
88Available for use in Manifest V3 or later.
88Available for use in Manifest V3 or later.
109Available for use in Manifest V3 or later.
?
74Available for use in Manifest V3 or later.
15.4Available for use in Manifest V3 or later.
? ?
109Available for use in Manifest V3 or later.
?
15.4Available for use in Manifest V3 or later.
?
icons Yes Yes 48 ? Yes 14 ? ? 48 ? 15 ?
incognito Yes ≤18 48 ? Yes No ? ? 48 ? No ?
manifest_version 4 14 48 ? 15 14 ? ? 48 ? 15 ?
name Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
offline_enabled Yes 79 No ? Yes No ? ? No ? No ?
omnibox Yes 79 52 ? Yes No ? ? No ? No ?
optional_permissions Yes 79 55 ? Yes 14 ? ? 55 ? 15 ?
options_page Yes 14 No ? 15 14 ? ? No ? 15 ?
options_ui 40 79 48 ? 27 14 ? ? 57 ? 15 ?
page_action
Yes["Since Chrome 49, page actions are displayed on the toolbar, rather than in the address bar.", "If an extension defines a page action, it is not allowed to define a browser action as well."]
14 48 ?
YesIf an extension defines a page action, it is not allowed to define a browser action as well.
14If an extension defines a page action, it is not allowed to define a browser action as well.
? ? Yes ?
15If an extension defines a page action, it is not allowed to define a browser action as well.
?
permissions Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
protocol_handlers No No 54 ? No No ? ? 54 ? No ?
short_name Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?
sidebar_action No No 54 ? 30 No ? ? No ? No ?
storage Yes 79 No ? No 14 ? ? No ? 15 ?
theme Yes 79 55 ? No No ? ? Yes ? No ?
theme_experiment No No 63 ? No No ? ? No ? No ?
user_scripts Yes 79 68 ? No No ? ? 68 ? No ?
version
YesValid Chrome versions are a subset of valid Firefox versions.
14 48 ? Yes 14 ? ? 48 ? 15 ?
version_name Yes 79 No ? Yes 14 ? ? No ? 15 ?
web_accessible_resources Yes 14 48 ? Yes 14 ? ? 48 ? 15 ?

For a full overview of all manifest keys and their sub-keys, see the full manifest.json browser compatibility table.

See also

permissions JavaScript API

© 2005–2023 MDN contributors.
Licensed under the Creative Commons Attribution-ShareAlike License v2.5 or later.
https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/manifest.json