package.json

Add-ons using the techniques described in this document are considered a legacy technology in Firefox. Don't use these techniques to develop new add-ons. Use WebExtensions instead. If you maintain an add-on which uses the techniques described here, consider migrating it to use WebExtensions.

From Firefox 53 onwards, no new legacy add-ons will be accepted on addons.mozilla.org (AMO).

From Firefox 57 onwards, WebExtensions will be the only supported extension type, and Firefox will not load other types.

Even before Firefox 57, changes coming up in the Firefox platform will break many legacy extensions. These changes include multiprocess Firefox (e10s), sandboxing, and multiple content processes. Legacy extensions that are affected by these changes should migrate to WebExtensions if they can. See the "Compatibility Milestones" document for more.

A wiki page containing resources, migration paths, office hours, and more, is available to help developers transition to the new technologies.

The package.json file contains manifest data for your add-on, providing not only descriptive information about the add-on for presentation in the Add-ons Manager, but other metadata required of add-ons.

Some of its entries, such as icon, name, and description, have direct analogues in the install manifest format, and entries from package.json are written into the install manifest when the add-on is built using jpm xpi.

Others, such as lib, permissions, and preferences, represent instructions to the jpm tool itself to generate and include particular code and data structures in your add-on.

Creating a manifest

The package.json file is initially generated in your add-on's root directory the first time you run jpm init. It looks like this (assuming the add-on's directory is "my-addon"):

{
  "name": "my-addon",
  "title": "my-addon",
  "id": "jid1-1FERGV45e4f4f@jetpack",
  "description": "a basic add-on",
  "author": "",
  "license": "MPL-2.0",
  "version": "0.1"
}

If you are using the new jpm tool, you can easily access manifest data from package.json by requiring it like any other module:

var title = require("./package.json").title;

Key reference

package.json may contain the following keys:

`author`	The name of the package's original author; this could be the name of a person or a company. Defaults to an empty string. It may include a optional URL in parentheses and an email address in angle brackets. This value will be used as the add-on's `em:creator` element in the `install.rdf` file generated by `cfx`. Note: jpm supports NodeJS people fields.
`contributors`	An array of additional `author` strings, identifying other contributors to the add-on. These values will be used as the add-on's `em:contributor` elements in its `install.rdf`. Note: This is deprecated along with `cfx`; it's not available when using jpm.
`dependencies`	A string or an array of strings specifying the names of packages that this add-on requires in order to function properly.
`description`	The add-on's description; this is a human-readable message describing what the add-on does. This defaults to the text "a basic add-on". This value will be used as the add-on's `em:description` element in its `install.rdf`.
`engines`	Object with supported applications (key) and required version numbers (value). The version number can both specify a minimum and maximum version separated by a space. `firefox`: Firefox Desktop `fennec`: Firefox for Android `thunderbird`: Thunderbird `seamonkey`: SeaMonkey Any application UUID Example: `"engines": { "firefox": ">= 38.0a1", "fennec": ">= 38.0a1" }`
`fullName`	Note: This is deprecated along with `cfx`; it's not available when using jpm. The full name of the package. It can contain spaces. If this key is present, its value will be used as the add-on's `em:name` element in its `install.rdf`.
`harnessClassID`	Note: This is deprecated along with `cfx`; it's not available when using jpm. String in the GUID format. This is used as a `classID` of the "harness service" XPCOM component. Defaults to a random GUID generated by `cfx`.
`hasEmbeddedWebExtension`	New in jpm 1.2.0. Boolean value: `true` if the add-on contains an embedded WebExtension.
`homepage`	The URL of the add-on's website. This value will be used as the add-on's `em:homepageURL` element in its `install.rdf`.
`icon`	The path to an image file containing the icon for the add-on. Optional: you can have no icon field in package.json and put your icon named "icon.png" in the root directory of your add-on. If no icon is specified, the standard add-on icon will be used by default. When using jpm, using a relative path to the data directory (to make it re-usable for add-on HTML content) does not work. You can generate the URL to your add-on icon in the data directory using the URL format below, where "your-addon-name" is the value in the name field of package.json. resource://@your-addon-name/data/your-icon-name.png This value will be used as the add-on's `em:iconURL` element in its `install.rdf`. The icon may be up to 48x48 pixels in size. A larger icon is will work, but may either scaled and possibly distorted) or might break parts of Firefox UI. (If you test this, please add the result here.) This can also be an object with the image size as key and the (absolute) location of the image as value. JPM looks for the sizes 64, 48 and 32.
`icon64`	Note: This is deprecated along with `cfx`; it's not available when using jpm. The path to an image containing the large icon for the add-on. Defaults to `icon64.png`. If you don't provide an icon here, the same icon as specified by `icon` will be used. This value will be used as the add-on's `em:icon64URL` element in its `install.rdf`. The icon may be up to 64x64 pixels in size.
`id`	A globally unique identifier for the add-on. This value will be used as the add-on's `em:id` element in its `install.rdf`. See the Program ID documentation.
`lib`	String representing the top-level module directory provided in this add-on. Defaults to "lib". Note: This is deprecated along with `cfx` and is not available when using jpm.
`license`	The name of the license under which the add-on is distributed, with an optional URL in parentheses. Defaults to `"MPL-2.0"`. Note: It is recommended that you use an SPDX license ID.
`locales`	An object holding JSON objects referenced by a locale name that use the following keys: `title`, `description` and `homepage`. These JSON objects will be used to localizations for the add-on's meta data shown within the Add-ons Manager. See the documentation for how to localize the add-on's meta data.
`main`	A string representing the name of a program module that is located in one of the top-level module directories specified by `lib`. Defaults to `"index.js"`.
`name`	The add-on's name. This name cannot contain spaces or periods, and defaults to the name of the parent directory. When the add-on is built as an XPI, if the `fullName` and `title` keys are not present, `name` is used as the add-on's `em:name` element in its `install.rdf`.
`packages`	Note: This is deprecated along with `cfx` and is not available when using jpm. A string pointing to a directory containing additional packages. Defaults to `"packages"`.
`permissions`	An object describing the set of permissions that the add-on needs. `private-browsing`: a boolean indicating whether or not the add-on supports private browsing. If this value is not `true` or is omitted, then the add-on will not see any private windows or objects, such as tabs, that are associated with private windows. See the documentation for the `private-browsing` module. `cross-domain-content`: a list of domains for which content scripts are given cross-domain privileges to access content in iframes or to make XMLHTTPRequests. See the documentation for enabling cross-domain content scripts. `multiprocess`: a Boolean value declaring whether this add-on is, or is not, compatible with multiprocess Firefox. Note the `multiprocess` permission is not supported by cfx.
`preferences`	An array of JSON objects that use the following keys: `name`,`type`, `value`, `title`, and `description`. These JSON objects will be used to create a preferences interface for the add-on in the Add-ons Manager unless the `preferencesURL` field is specified. See the documentation for the `simple-prefs` module.
`preferencesURL`	The URL where the "Preferences" button of your add-on in the Add-ons Manager will point to. Use this to specify a custom preferences page instead of the built-in UI provided by the Add-on Manager.
`preferences-branch`	Use this to specify an alternative branch for your add-on's simple-prefs. See "Simple-prefs in the preferences system" for more details.
`title`	The human-readable title of the package; this can contain spaces. If this key is present, its value will be used as the add-on's `em:name` element in its `install.rdf`.
`translators`	An array of strings listing the people who contributed to the localization of this add-on. These values will be used as the add-on's `em:translator` elements in its `install.rdf`. Note: jpm supports NodeJS people fields.
`unpack`	Same as the `unpack` in an `install.rdf` file. Useful when the extension contains binaries.
`updateKey`	Same as the `updateKey` in an `install.rdf` file. See Supporting updates for self-hosted add-ons. Note: This key is only available with jpm.
`updateLink`	Same as the `updateLink` for an `update.rdf` file. Previously was `--update-link in cfx`. See Supporting updates for self-hosted add-ons. Note: This key is only available with jpm.
`updateURL`	Same as the `updateURL` for an `install.rdf` file. See Supporting updates for self-hosted add-ons. Note: This key is only available with jpm.
`version`	String representing the version of the add-on. Defaults to "0.0.1". This value is used as the add-on's `em:version` element in its `install.rdf`. Note: For jpm the version must be a valid semver.

Reorder package.json

The package.json file is simple format. You can describe Keys in any order. But sometimes it should be better reorder it for improve readability. A tool "fixpack" will reorder your package.json as follows:

name first
description second
version third
author fourth
all other keys in alphabetical order
dependencies and devDependencies sorted alphabetically
newline at the end of the file

More details here:
"GitHub - HenrikJoreteg/fixpack: A package.json file scrubber for the truly insane."
https://github.com/henrikjoreteg/fixpack

Creating a manifest

Key reference

Reorder package.json

Document Tags and Contributors