Please note, this is a STATIC archive of website developer.mozilla.org from 03 Nov 2016, cach3.com does not collect or store any user information, there is no "phishing" involved.
Add-ons

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

A 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.

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

Document Tags and Contributors

Tags: 
 Contributors to this page: wbamberg, lgreco, Makyen, ntim, backy0175, freaktechnik, Sebastianz, rolfedh, nikolas, Dietrich, omivore, marcows, AlexPl, jsantell, maybe, evold, Foolswisdom, Sheppy, mathieu_agopian, Canuckistani, rubo77, Ctulek, tomica, Delapouite
 Last updated by: wbamberg,