node/deps/npm/node_modules/read-package-json/README.md

read-package-json

This is the thing that npm uses to read package.json files. It validates some stuff, and loads some default things.

It keeps a cache of the files you've read, so that you don't end up reading the same package.json file multiple times.

Note that if you just want to see what's literally in the package.json file, you can usually do var data = require('some-module/package.json').

This module is basically only needed by npm, but it's handy to see what npm will see when it looks at your package.

Usage

var readJson = require('read-package-json')

readJson('/path/to/package.json', function (er, data) {
  if (er) {
    console.error("There was an error reading the file")
    return
  }

  console.error('the package data is', data)
}

readJson(file, cb)

• file {String} The path to the package.json file
• cb {Function}

Reads the JSON file and does the things.

package.json Fields

See man 5 package.json or npm help json.

readJson.log

By default this is a reference to the npmlog module. But if that module can't be found, then it'll be set to just a dummy thing that does nothing.

Replace with your own {log,warn,error} object for fun loggy time.

readJson.extras(file, data, cb)

Run all the extra stuff relative to the file, with the parsed data.

Modifies the data as it does stuff. Calls the cb when it's done.

readJson.extraSet = [fn, fn, ...]

Array of functions that are called by extras. Each one receives the arguments fn(file, data, cb) and is expected to call cb(er, data) when done or when an error occurs.

Order is indeterminate, so each function should be completely independent.

Mix and match!

readJson.cache

The lru-cache object that readJson uses to not read the same file over and over again. See lru-cache for details.

Other Relevant Files Besides package.json

Some other files have an effect on the resulting data object, in the following ways:

README?(.*)

If there is a README or README.* file present, then npm will attach a readme field to the data with the contents of this file.

Owing to the fact that roughly 100% of existing node modules have Markdown README files, it will generally be assumed to be Markdown, regardless of the extension. Please plan accordingly.

server.js

If there is a server.js file, and there is not already a scripts.start field, then scripts.start will be set to node server.js.

AUTHORS

If there is not already a contributors field, then the contributors field will be set to the contents of the AUTHORS file, split by lines, and parsed.

bindings.gyp

If a bindings.gyp file exists, and there is not already a scripts.install field, then the scripts.install field will be set to node-gyp rebuild.

wscript

If a wscript file exists, and there is not already a scripts.install field, then the scripts.install field will be set to node-waf clean ; node-waf configure build.

Note that the bindings.gyp file supercedes this, since node-waf has been deprecated in favor of node-gyp.

index.js

If the json file does not exist, but there is a index.js file present instead, and that file has a package comment, then it will try to parse the package comment, and use that as the data instead.

A package comment looks like this:

/**package
 * { "name": "my-bare-module"
 * , "version": "1.2.3"
 * , "description": "etc...." }
 **/

// or...

/**package
{ "name": "my-bare-module"
, "version": "1.2.3"
, "description": "etc...." }
**/

The important thing is that it starts with /**package, and ends with **/. If the package.json file exists, then the index.js is not parsed.

{directories.man}/*.[0-9]

If there is not already a man field defined as an array of files or a single file, and there is a directories.man field defined, then that directory will be searched for manpages.

Any valid manpages found in that directory will be assigned to the man array, and installed in the appropriate man directory at package install time, when installed globally on a Unix system.

{directories.bin}/*

If there is not already a bin field defined as a string filename or a hash of <name> : <filename> pairs, then the directories.bin directory will be searched and all the files within it will be linked as executables at install time.

When installing locally, npm links bins into node_modules/.bin, which is in the PATH environ when npm runs scripts. When installing globally, they are linked into {prefix}/bin, which is presumably in the PATH environment variable.