Package Specification

A package is a directory that, at minimum, contains a JSON file called package.json. This file is also referred to as the package manifest.

The Package Manifest

package.json may contain the following keys:

  • name - the name of the package. The package system will only load one package with a given name. This name cannot contain spaces or periods. The name defaults to the name of the parent directory. If the package is ever built as an XPI and the fullName key is not present, this is used as the add-on's em:name element in its install.rdf.

  • fullName - the full name of the package. It can contain spaces. If the package is ever built as an XPI, this is used as the add-on's em:name element in its install.rdf.

  • description - a String describing the package. If the package is ever built as an XPI, this is used as the add-on's em:description element in its install.rdf.

  • author - the original author of the package. The author may be a String including an optional URL in parentheses and optional email address in angle brackets. If the package is ever built as an XPI, this is used as the add-on's em:creator element in its install.rdf.

  • contributors - may be an Array of additional author Strings.

  • homepage - the URL of the package's website.

  • icon - the relative path from the root of the package to a PNG file containing the icon for the package. By default, this is icon.png. If the package is built as an XPI, this is used as the add-on's icon to display in the Add-on Manager's add-ons list. This key maps on to the iconURL entry in the Install Manifest, so the icon may be up to 48x48 pixels in size.

  • icon64 - the relative path from the root of the package to a PNG file containing the icon64 for the package. By default, this is icon64.png. If the package is built as an XPI, this is used as the add-on's icon to display in the Addon Manager's add-on details view. This key maps on to the icon64URL entry in the Install Manifest, so the icon should be 64x64 pixels in size.

  • preferences - experimental An array of JSON objects that use the following keys name, type, value, title, and description. These JSON objects will be used to automatically create a preferences interface for the addon in the Add-ons Manager. For more information see the documentation of simple-prefs.

  • license - the name of the license as a String, with an optional URL in parentheses.

  • id - a globally unique identifier for the package. When the package is built as an XPI, this is used as the add-on's em:id element in its install.rdf. See the Program ID page.

  • version - a String representing the version of the package. If the package is ever built as an XPI, this is used as the add-on's em:version element in its install.rdf.

  • dependencies - a String or Array of Strings representing package names that this package requires in order to function properly.

  • lib - a String representing the top-level module directory provided in this package. Defaults to "lib".

  • tests - a String representing the top-level module directory containing test suites for this package. Defaults to "tests".

  • packages - a String or Array of Strings representing paths to directories containing additional packages, defaults to "packages".

  • 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 "main".

  • harnessClassID - a String in the GUID format: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx, where x represents a single hexadecimal digit. It is used as a classID (CID) of the "harness service" XPCOM component. Defaults to a random GUID generated by cfx.

Documentation

A package may optionally contain a Markdown-formatted file called README.md in its root directory. Package-browsing tools may display this file to developers.

Additionally, Markdown files can be placed in an optional docs directory. When package-browsing tools are asked to show the documentation for a module, they will look in this directory for a .md file with the module's name. Thus, for instance, if a user browses to a module at lib/foo/bar.js, the package-browsing tool will look for a file at docs/foo/bar.js to represent the module's API documentation.

Data Resources

Packages may optionally contain a directory called data into which arbitrary files may be placed, such as images or text files. The URL for these resources may be reached using the self module.