• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# read-package-json
2
3This is the thing that npm uses to read package.json files.  It
4validates some stuff, and loads some default things.
5
6It keeps a cache of the files you've read, so that you don't end
7up reading the same package.json file multiple times.
8
9Note that if you just want to see what's literally in the package.json
10file, you can usually do `var data = require('some-module/package.json')`.
11
12This module is basically only needed by npm, but it's handy to see what
13npm will see when it looks at your package.
14
15## Usage
16
17```javascript
18var readJson = require('read-package-json')
19
20// readJson(filename, [logFunction=noop], [strict=false], cb)
21readJson('/path/to/package.json', console.error, false, function (er, data) {
22  if (er) {
23    console.error("There was an error reading the file")
24    return
25  }
26
27  console.error('the package data is', data)
28});
29```
30
31## readJson(file, [logFn = noop], [strict = false], cb)
32
33* `file` {String} The path to the package.json file
34* `logFn` {Function} Function to handle logging.  Defaults to a noop.
35* `strict` {Boolean} True to enforce SemVer 2.0 version strings, and
36  other strict requirements.
37* `cb` {Function} Gets called with `(er, data)`, as is The Node Way.
38
39Reads the JSON file and does the things.
40
41## `package.json` Fields
42
43See `man 5 package.json` or `npm help json`.
44
45## readJson.log
46
47By default this is a reference to the `npmlog` module.  But if that
48module can't be found, then it'll be set to just a dummy thing that does
49nothing.
50
51Replace with your own `{log,warn,error}` object for fun loggy time.
52
53## readJson.extras(file, data, cb)
54
55Run all the extra stuff relative to the file, with the parsed data.
56
57Modifies the data as it does stuff.  Calls the cb when it's done.
58
59## readJson.extraSet = [fn, fn, ...]
60
61Array of functions that are called by `extras`.  Each one receives the
62arguments `fn(file, data, cb)` and is expected to call `cb(er, data)`
63when done or when an error occurs.
64
65Order is indeterminate, so each function should be completely
66independent.
67
68Mix and match!
69
70## Other Relevant Files Besides `package.json`
71
72Some other files have an effect on the resulting data object, in the
73following ways:
74
75### `README?(.*)`
76
77If there is a `README` or `README.*` file present, then npm will attach
78a `readme` field to the data with the contents of this file.
79
80Owing to the fact that roughly 100% of existing node modules have
81Markdown README files, it will generally be assumed to be Markdown,
82regardless of the extension.  Please plan accordingly.
83
84### `server.js`
85
86If there is a `server.js` file, and there is not already a
87`scripts.start` field, then `scripts.start` will be set to `node
88server.js`.
89
90### `AUTHORS`
91
92If there is not already a `contributors` field, then the `contributors`
93field will be set to the contents of the `AUTHORS` file, split by lines,
94and parsed.
95
96### `bindings.gyp`
97
98If a bindings.gyp file exists, and there is not already a
99`scripts.install` field, then the `scripts.install` field will be set to
100`node-gyp rebuild`.
101
102### `index.js`
103
104If the json file does not exist, but there is a `index.js` file
105present instead, and that file has a package comment, then it will try
106to parse the package comment, and use that as the data instead.
107
108A package comment looks like this:
109
110```javascript
111/**package
112 * { "name": "my-bare-module"
113 * , "version": "1.2.3"
114 * , "description": "etc...." }
115 **/
116
117// or...
118
119/**package
120{ "name": "my-bare-module"
121, "version": "1.2.3"
122, "description": "etc...." }
123**/
124```
125
126The important thing is that it starts with `/**package`, and ends with
127`**/`.  If the package.json file exists, then the index.js is not
128parsed.
129
130### `{directories.man}/*.[0-9]`
131
132If there is not already a `man` field defined as an array of files or a
133single file, and
134there is a `directories.man` field defined, then that directory will
135be searched for manpages.
136
137Any valid manpages found in that directory will be assigned to the `man`
138array, and installed in the appropriate man directory at package install
139time, when installed globally on a Unix system.
140
141### `{directories.bin}/*`
142
143If there is not already a `bin` field defined as a string filename or a
144hash of `<name> : <filename>` pairs, then the `directories.bin`
145directory will be searched and all the files within it will be linked as
146executables at install time.
147
148When installing locally, npm links bins into `node_modules/.bin`, which
149is in the `PATH` environ when npm runs scripts.  When
150installing globally, they are linked into `{prefix}/bin`, which is
151presumably in the `PATH` environment variable.
152