95

I have seen (don't remember where) a package.json file with custom keys starting with an underscore:

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

Are you allowed to do this? Is it still valid? If this is allowed, is there any documentation on the rules?

Thanks!

0

2 Answers 2

142

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:

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.

8
  • 3
    Thanks for the insight. Is there any reason you recommend "org_example" instead of "org.example" – or an XML-namespace-like "http://example.org"?
    – tomekwi
    May 15, 2015 at 9:11
  • 8
    @tomekwi: You could use org.example or http://example.org, but, given that the JSON key names are also JavaScript object property names, it would make it awkward to access these properties later, because you'd have to use something like pkg['org.example'], because the more natural pkg.<propertyname> syntax wouldn't work with them.
    – mklement0
    May 15, 2015 at 13:14
  • 2
    @tomekwi: As for @example: I suppose that would work if you use your / your organization's npm username. Note that we're talking about a self-chosen convention in any case here, so personally I'd go for the reverse-domain-notation, because it is (a) common practice in other contexts), and (b) "more unique" than an npm username.
    – mklement0
    May 15, 2015 at 13:21
  • 1
    @tomekwi: Yes, the very point of using _ is for, e.g., org_example to be recognized as a single word, forming a regular JS property name. You're referring to - (hyphen) chars. in domain names, which indeed wouldn't work. However, you can replace - instances with _ instances as well; while this renders the transformation potentially non-reversible, it still strikes me as preferable to property names such as http://domain-name.org, especially in view of the fact that using - in domain names is increasingly rare. However, this is ultimately a matter of preference.
    – mklement0
    May 16, 2015 at 22:19
  • 3
    I think the NPM team should choose a reserved property for this. Like "config", I don't know
    – GabrielBB
    Jan 13, 2020 at 6:48
20

Given the nature of JSON and this statement from the Nodejitsu documentation I don't see anything wrong with that.

NPM itself is only aware of two fields in the package.json:

{
   "name" : "barebones",
   "version" : "0.0.0",
}

NPM also cares about a couple of fields listed here. So as long as it is valid JSON and doesn't interfere with Node.js or NPM everything should be alright and valid.

Node's awareness of package.json files seems extends to the main field. Ref.

 { "name" : "some-library",
   "main" : "./lib/some-library.js" }

If this was in a folder at ./some-library, then require('./some-library') would attempt to load ./some-library/lib/some-library.js.

This is the extent of Node's awareness of package.json files.

To avoid possible conflicts you should prefixing your keys with some character or word. It is not recommended to use an underscore (_) or dollar sign ($) as those are reserved character prefixes, but other choices are viable.

3

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service and acknowledge that you have read and understand our privacy policy and code of conduct.

Not the answer you're looking for? Browse other questions tagged or ask your own question.