Add custom metadata or config to package.json, is it valid?

tl;dr:

  • Yes, you’re allowed to add custom entries to package.json.
  • Choose a key name:
    • not already defined (details below)
    • not reserved for future use (details below)
    • avoid prefixes _ and $
    • and preferably use a single top-level key in which to nest your custom entries.

E.g., if you own domain example.org, you could store a custom random key as follows, inside a top-level key in reverse-domain-name notation with _ substituted for . and, if applicable, -(see comments) (e.g., org_example):

{
    "name": "application-name"
  , "version": "0.0.1"
  , "private": true
  , "dependencies": {
      "express": "2.4.7"
    , "jade": ">= 0.0.1"
  }  
  , "org_example": {
      "random": true
  }
}

To read such custom properties, use the following technique:

require("./package.json").org_example.random // -> true

npm‘s package.json file format mostly complies with the CommonJS package specification:

  • keys that npm currently uses: https://docs.npmjs.com/files/package.json
  • keys defined in the spec: http://wiki.commonjs.org/wiki/Packages/1.1

As for choosing custom keys: the CommonJS package specification states (emphasis mine):

The following fields are reserved for future expansion: build, default, email, external, files, imports, maintainer, paths, platform, require, summary, test, using, downloads, uid.

Extensions to the package descriptor specification should strive to avoid collisions for future standard names by name-spacing their properties with innocuous names that do not have meanings relevant to general package management.

The following fields are reserved for package registries to use at their discretion: id, type.
All properties beginning with _ or $ are also reserved for package registries to use at their discretion.

Leave a Comment

Hata!: SQLSTATE[HY000] [1045] Access denied for user 'divattrend_liink'@'localhost' (using password: YES)