1. File structure
Once unpacked from the distribution format, a WebExtension is a directory containing a number of files.
Note: In some operating systems, filenames are case insensitive. This can lead to naming collisions.
1.1. manifest.json
A Manifest file.
1.2. _locales subdirectory
An optional directory containing strings as defined in localization.
1.3. Other files
An extension may also contain other files, such as those referenced in the content_scripts and background part of the Manifest.
2. Manifest
A WebExtension must have a manifest file at its root directory.
2.1. Manifest file
A manifest file is a [JSON] document named manifest.json. Malformed JSON files are not supported. Note that some implementors may accept comments, represented by any content following // outside of a JSON string.
2.2. Manifest keys
If manifest keys that are not defined in this specification are specified, implementors must ignore those keys.
If manifest keys that are defined in this specification are specified with a different JSON type than defined in this specification, implementors must ignore those keys.
The following keys must be considered valid:
-
manifest_version: required. -
name: required. -
version: required. -
default_locale: required under some conditions. -
background: optional -
commands: optional -
content_scripts: optional -
content_security_policy: optional -
description: optional -
icons: optional -
optional_permissions: optional -
options_ui: optional -
permissions: optional -
short_name: optional -
web_accessible_resources: optional -
devtools_page: optional -
externally_connectable: optional
The following keys must be considered valid in Manifest V3:
-
host_permissions: optional -
optional_host_permissions: optional
2.2.1. Key manifest_version
This key must be present.
2.2.2. Key name
Name of the extension used in the browser’s user interface. This should be the full name used to identify the extension. See also short_name.
This key must be present. This property can be localized.
2.2.3. Key version
This key must be present.
2.2.4. Key permissions
This key may be present.
2.2.5. Key optional_permissions
This key may be present.
2.2.6. Key host_permissions
This key may be present.
2.2.7. Key optional_host_permissions
This key may be present.
2.2.8. Key default_locale
This key must be present if the _locales subdirectory is present, must be absent otherwise.
2.2.9. Key background
This key may be present.
2.2.10. Key commands
This key may be present.
2.2.11. Key content_scripts
This key may be present.
2.2.12. Key content_security_policy
This key may be present.
2.2.13. Key description
This key may be present.
2.2.14. Key icons
This key may be present.
2.2.15. Key options_ui
This key may be present.
2.2.16. Key short_name
The short name of the extension. This value should be used in contexts where name is too long to use in full. If short_name is not provided, manifest consumers should use a truncated version of name.
This key may be present. This property can be localized.
2.2.17. Key web_accessible_resources
This key may be present.
2.2.18. Key externally_connectable
This key may be present.
2.2.19. Key devtools_page
This key may be present.
2.3. Reserved file names
Filenames beginning with an underscore (_) are reserved for use by user agent.
3. Isolated worlds
4. Unavailable APIs
5. The browser global
6. Extension origin
7. Localization
The _locales subdirectory of a WebExtension can contain strings for internationalization purposes.
Specify localization handling. [Issue #62]