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:

action (Manifest V3 and above)
author
background
browser_action (Manifest V2 only)
browser_specific_settings
chrome_settings_overrides
chrome_url_overrides
commands
content_scripts
content_security_policy
declarative_net_request
default_locale
description
developer
devtools_page
dictionaries
externally_connectable
homepage_url
host_permissions (Manifest V3 and above)
icons
incognito
manifest_version
name
offline_enabled
omnibox
optional_host_permissions (Manifest V3 and above)
optional_permissions
options_page
options_ui
page_action (Manifest V2 only in Chrome)
permissions
protocol_handlers
short_name
sidebar_action
storage
theme
theme_experiment
user_scripts (Manifest V2 only)
version
version_name
web_accessible_resources

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.

json

{
  "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

BCD tables only load in the browser

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