Permalink
Newer
Older
100644 572 lines (571 sloc) 14.3 KB
1
.\" Generated with Ronnjs/v0.1
2
.\" http://github.com/kapouer/ronnjs/
Feb 7, 2011
4
.TH "NPM\-JSON" "1" "February 2011" "" ""
7
\fBnpm-json\fR \-\- Specifics of npm\'s package\.json handling
10
npm aims to implement the commonjs Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec\. However, some
11
adjustments have been made, which may eventually be unmade, but hopefully will
12
be incorporated into the spec\.
15
This document is all you need to know about what\'s required in your package\.json
16
file\.
Aug 25, 2010
18
.P
19
A lot of the behavior described in this document is affected by the config
20
settings described in \fBnpm help config\fR\|\.
21
.
22
.SH "name"
23
The \fImost\fR important things in your package\.json are the name and version fields\.
26
The name is what your thing is called\. Some tips:
29
Don\'t put "js" or "node" in the name\. It\'s assumed that it\'s js, since you\'re
30
writing a package\.json file, and you can specify the engine using the "engines"
31
field\. (See below\.)
34
The name ends up being part of a URL, an argument on the command line, and a
35
folder name\. So, don\'t use characters that are annoying in those contexts, like
36
funny UTF things or parentheses or slashes, or else it\'ll break\.
39
The name will probably be passed as an argument to require(), so it should
40
be something short, but also reasonably descriptive\.
43
You may want to check the npm registry to see if there\'s something by that name
44
already, before you get too attached to it\. http://registry\.npmjs\.org/
48
.SH "version"
49
The \fImost\fR important things in your package\.json are the name and version fields\.
Feb 15, 2011
52
Version must be semver \fIhttps://github\.com/isaacs/semver\fR\-compliant\.
53
npm assumes that you\'ve
54
read the semver page, and that you comply with it\.
55
.
56
.P
57
Here\'s how it deviates from what\'s on semver\.org:
59
.IP "\(bu" 4
60
Versions can start with "v"
63
A numeric item separated from the main three\-number version by a hyphen
64
will be interpreted as a "build" number, and will \fIincrease\fR the version\.
65
But, if the tag is not a number separated by a hyphen, then it\'s treated
66
as a pre\-release tag, and is \fIless than\fR the version without a tag\.
67
So, 0\.1\.2\-7 > 0\.1\.2\-6 > 0\.1\.2 > 0\.1\.2beta
72
This is a little bit confusing to explain, but matches what you see in practice
73
when people create tags in git like "v1\.2\.3" and then do "git describe" to generate
74
a patch version\. (This is how node\'s versions are generated, and has driven this
75
design\.)
78
Put a description in it\. It\'s a string\. This helps people discover your
79
package, as it\'s listed in \fBnpm ls\fR\|\.
80
.
81
.SH "keywords"
82
Put keywords in it\. It\'s an array of strings\. This helps people
83
discover your package as it\'s listed in \fBnpm ls\fR\|\.
84
.
85
.SH "homepage"
86
The url to the project homepage\.
87
.
88
.P
89
\fBNOTE\fR: This is \fInot\fR the same as "url"\. If you put a "url" field,
90
then the registry will think it\'s a redirection to your package that has
91
been published somewhere else, and spit at you\.
92
.
93
.P
94
Literally\. Spit\. I\'m so not kidding\.
95
.
96
.SH "people fields: author, contributors"
97
The "author" is one person\. "contributors" is an array of people\. A "person"
98
is an object with a "name" field and optionally "url" and "email", like this:
99
.
100
.IP "" 4
101
.
102
.nf
103
{ "name" : "Barney Rubble"
104
, "email" : "b@rubble\.com"
105
, "url" : "http://barnyrubble\.tumblr\.com/"
106
}
107
.
108
.fi
109
.
110
.IP "" 0
111
.
112
.P
113
Or you can shorten that all into a single string, and npm will parse it for you:
114
.
115
.IP "" 4
116
.
117
.nf
118
"Barney Rubble <b@rubble\.com> (http://barnyrubble\.tumblr\.com/)
119
.
120
.fi
121
.
122
.IP "" 0
123
.
124
.P
125
Both email and url are optional either way\.
126
.
127
.P
128
npm also sets a top\-level "maintainers" field with your npm user info\.
129
.
Jan 5, 2011
130
.SH "files"
131
The "files" field is an array of files to include in your project\. If
132
you name a folder in the array, then it will also include the files
133
inside that folder\. The default is just \fB[""]\fR which includes the
134
entire package folder in the tarball, but you may want to only include
135
specific things\.
136
.
137
.P
Feb 7, 2011
138
If you specify bins or man pages, then those will be
Jan 5, 2011
139
automatically added to the files array, even if they would not
140
ordinarily be included\.
141
.
142
.P
143
You can also provide a "\.npmignore" file in the root of your package,
144
which will keep files from being included, even if they would be picked
145
up by the files array\.
146
.
148
The main field is a module ID that is the primary entry point to your program\.
149
That is, if your package is named \fBfoo\fR, and a user installs it, and then does \fBrequire("foo")\fR, then your main module\'s exports object will be returned\.
152
This should be a module ID relative to the root of your package folder\.
155
For most modules, it makes the most sense to have a main script and often not
156
much else\.
157
.
158
.SH "bin"
159
A lot of packages have one or more executable files that they\'d like to
160
install into the PATH\. npm makes this pretty easy (in fact, it uses this
161
feature to install the "npm" executable\.)
162
.
163
.P
164
To use this, supply a \fBbin\fR field in your package\.json which is a map of
165
command name to local file name\. On install, npm will link that file into
166
place right next to wherever node is installed\. (Presumably, this is in your
167
PATH, and defaults to \fB/usr/local/bin\fR\|\.) On activation, the versioned file
168
will get linked to the main filename (just like how the main\.js stuff works,
169
but with an executable in the PATH\.)
170
.
171
.P
172
For example, npm has this:
173
.
174
.IP "" 4
175
.
176
.nf
177
{ "bin" : { "npm" : "\./cli\.js" } }
178
.
179
.fi
180
.
181
.IP "" 0
182
.
183
.P
184
So, when you install npm, it\'ll create a symlink from the \fBcli\.js\fR script to \fB/usr/local/bin/npm\-version\fR\|\. Then, when you activate that version, it\'ll
185
create a symlink from \fB/usr/local/bin/npm\-version\fR to \fB/usr/local/bin/npm\fR\|\.
187
.P
188
Notice that if the executable file is interpreted by node (i\.e\., specifying
189
node in the shebang line), npm actually installs a shim instead of symlinking
190
it, which causes expressions \fBrequire\.main === module\fR and \fBmodule\.id === "\."\fR
191
evaluate to \fBfalse\fR within the file\. This seems unable to be resolved until
192
node provides a "flexible \fBrequire()\fR"\.
193
.
194
.P
195
Shortcut: If you have a single executable, and its name is already what you
196
want it to be, then you can just supply it as a string\. For example:
197
.
198
.IP "" 4
199
.
200
.nf
201
{ "bin" : "\./path/to/program" }
202
.
203
.fi
204
.
205
.IP "" 0
206
.
207
.P
208
would be the same as this:
209
.
210
.IP "" 4
211
.
212
.nf
213
{ "bin" : { "program" : "\./path/to/program" } }
214
.
215
.fi
216
.
217
.IP "" 0
218
.
Aug 25, 2010
219
.SH "man"
220
Specify either a single file or an array of filenames to put in place for the \fBman\fR program to find\.
221
.
222
.P
223
If only a single file is provided, then it\'s installed such that it is the
224
result from \fBman <pkgname>\fR, regardless of its actual filename\. For example:
225
.
226
.IP "" 4
227
.
228
.nf
229
{ "name" : "foo"
230
, "man" : "\./man/doc\.1"
231
}
232
.
233
.fi
234
.
235
.IP "" 0
236
.
237
.P
238
would link the \fB\|\./man/doc\.1\fR file in such that it is the target for \fBman foo\fR
239
.
240
.P
241
If the filename doesn\'t start with the package name, then it\'s prefixed\.
242
So, this:
243
.
244
.IP "" 4
245
.
246
.nf
247
{ "name" : "foo"
248
, "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
249
}
250
.
251
.fi
252
.
253
.IP "" 0
254
.
255
.P
256
will create files to do \fBman foo\fR and \fBman foo\-bar\fR\|\.
257
.
258
.P
259
Man files must end with a number, and optionally a \fB\|\.gz\fR suffix if they are
260
compressed\. The number dictates which man section the file is installed into\.
261
.
262
.IP "" 4
263
.
264
.nf
265
{ "name" : "foo"
266
, "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
267
}
268
.
269
.fi
270
.
271
.IP "" 0
272
.
273
.P
274
will create entries for \fBman foo\fR and \fBman 2 foo\fR
275
.
276
.SH "directories"
277
The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
278
few ways that you can indicate the structure of your package using a \fBdirectories\fR
279
hash\. If you look at npm\'s package\.json \fIhttp://registry\.npmjs\.org/npm/latest\fR,
280
you\'ll see that it has directories for doc, lib, and man\.
281
.
282
.P
283
In the future, this information may be used in other creative ways\.
284
.
285
.SS "directories\.lib"
Feb 7, 2011
286
If you specify a "lib" directory, then the lib
287
folder will be walked and any \fI\|\.js or \fR\|\.node files found will be exposed as a
Aug 25, 2010
288
default module hash\.
Feb 7, 2011
291
\fBThe lib directory mapping will be deprecated soon\. Please do not rely
292
on it\.\fR
Aug 25, 2010
294
.SS "directories\.bin"
295
If you specify a "bin" directory, then all the files in that folder will be used
296
as the "bin" hash\.
297
.
298
.P
299
If you have a "bin" hash already, then this has no effect\.
300
.
301
.SS "directories\.man"
302
A folder that is full of man pages\. Sugar to generate a "man" array by walking the folder\.
303
.
304
.SS "directories\.doc"
305
Put markdown files in here\. Eventually, these will be displayed nicely, maybe, someday\.
306
.
307
.SS "directories\.example"
308
Put example scripts in here\. Someday, it might be exposed in some clever way\.
309
.
310
.SH "repository"
311
Specify the place where your code lives\. This is helpful for people who want to
312
contribute, as well as perhaps maybe being the underpinning of some magical "track
313
this package on git" feature someday maybe if somebody wants to write it ever\.
314
.
315
.P
316
Do it like this:
317
.
318
.IP "" 4
319
.
320
.nf
321
"repository" :
322
{ "type" : "git"
323
, "url" : "http://github\.com/isaacs/npm\.git"
324
}
325
"repository" :
326
{ "type" : "svn"
327
, "url" : "http://v8\.googlecode\.com/svn/trunk/"
328
}
329
.
330
.fi
331
.
332
.IP "" 0
333
.
334
.P
335
The URL should be a publicly available (perhaps read\-only) url that can be handed
336
directly to a VCS program without any modification\. It should not be a url to an
337
html project page that you put in your browser\. It\'s for computers\.
338
.
339
.P
340
Here are some examples of Doing It Wrong:
341
.
342
.IP "" 4
343
.
344
.nf
345
WRONG!
346
"repository" :
347
{ "type" : "git"
348
, "url" : "git@github\.com:isaacs/npm\.git" <\-\- THIS IS PRIVATE!
349
}
350
ALSO WRONG!
351
"repository" :
352
{ "type" : "git"
353
, "url" : "http://github\.com/isaacs/npm" <\-\- THIS IS WEBPAGE!
354
}
355
This is ok, but completely unnecessary:
356
"repository" :
357
{ "type" : "git"
358
, "url" : "http://github\.com/isaacs/npm\.git"
359
, "private" : "git@github\.com:isaacs/npm\.git"
360
, "web" : "http://github\.com/isaacs/npm"
361
}
366
.
367
.SH "scripts"
368
The "scripts" member is an object hash of script commands that are run
369
at various times in the lifecycle of your package\. The key is the lifecycle
370
event, and the value is the command to run at that point\.
373
See \fBnpm help scripts\fR to find out more about writing package scripts\.
374
.
Jan 5, 2011
375
.SH "config"
376
A "config" hash can be used to set configuration
377
parameters used in package scripts that persist across upgrades\. For
378
instance, if a package had the following:
379
.
380
.IP "" 4
381
.
382
.nf
383
{ "name" : "foo"
384
, "config" : { "port" : "8080" } }
385
.
386
.fi
387
.
388
.IP "" 0
389
.
390
.P
391
and then had a "start" command that then referenced the \fBnpm_package_config_port\fR environment variable, then the user could
392
override that by doing \fBnpm config set foo:port 8001\fR\|\.
393
.
394
.P
395
See \fBnpm help config\fR and \fBnpm help scripts\fR for more on package
396
configs\.
397
.
398
.SH "dependencies"
399
Dependencies are specified with a simple hash of package name to version
Feb 7, 2011
400
range\. The version range is EITHER a string which has one or more
401
space\-separated descriptors, OR a range like "fromVersion \- toVersion"
404
Version range descriptors may be any of the following styles, where "version"
405
is a semver compatible version identifier\.
406
.
407
.IP "\(bu" 4
408
\fBversion\fR Must match \fBversion\fR exactly
409
.
410
.IP "\(bu" 4
411
\fB=version\fR Same as just \fBversion\fR
412
.
413
.IP "\(bu" 4
414
\fB>version\fR Must be greater than \fBversion\fR
415
.
416
.IP "\(bu" 4
417
\fB>=version\fR etc
418
.
419
.IP "\(bu" 4
420
\fB<version\fR
421
.
422
.IP "\(bu" 4
423
\fB<=version\fR
424
.
425
.IP "\(bu" 4
Jan 7, 2011
426
\fB~version\fR See \'Tilde Version Ranges\' below
427
.
428
.IP "\(bu" 4
429
\fB1\.2\.x\fR See \'X Version Ranges\' below
430
.
431
.IP "\(bu" 4
432
\fBhttp://\.\.\.\fR See \'URLs as Dependencies\' below
433
.
434
.IP "\(bu" 4
435
\fB*\fR Matches any version
436
.
437
.IP "\(bu" 4
438
\fB""\fR (just an empty string) Same as \fB*\fR
439
.
440
.IP "\(bu" 4
441
\fBversion1 \- version2\fR Same as \fB>=version1 <=version2\fR\|\.
443
.IP "\(bu" 4
444
\fBrange1 || range2\fR Passes if either range1 or range2 are satisfied\.
445
.
446
.IP "" 0
447
.
448
.P
449
For example, these are all valid:
450
.
451
.IP "" 4
452
.
453
.nf
454
{ "dependencies" :
455
{ "foo" : "1\.0\.0 \- 2\.9999\.9999"
456
, "bar" : ">=1\.0\.2 <2\.1\.2"
457
, "baz" : ">1\.0\.2 <=2\.3\.4"
458
, "boo" : "2\.0\.1"
459
, "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
Jan 7, 2011
460
, "asd" : "http://asdf\.com/asdf\.tar\.gz"
461
, "til" : "~1\.2"
462
, "elf" : "~1\.2\.3"
463
, "two" : "2\.x"
464
, "thr" : "3\.3\.x"
465
}
466
}
467
.
468
.fi
469
.
470
.IP "" 0
471
.
Jan 7, 2011
472
.SS "Tilde Version Ranges"
473
A range specifier starting with a tilde \fB~\fR character is matched against
474
a version in the following fashion\.
475
.
476
.IP "\(bu" 4
477
The version must be at least as high as the range\.
478
.
479
.IP "\(bu" 4
480
The version must be less than the next major revision above the range\.
481
.
482
.IP "" 0
483
.
484
.P
485
For example, the following are equivalent:
486
.
487
.IP "\(bu" 4
488
\fB"~1\.2\.3" = ">=1\.2\.3 <1\.3\.0"\fR
489
.
490
.IP "\(bu" 4
491
\fB"~1\.2" = ">=1\.2\.0 <2\.0\.0"\fR
492
.
493
.IP "\(bu" 4
494
\fB"~1" = ">=1\.0\.0 <2\.0\.0"\fR
495
.
496
.IP "" 0
497
.
498
.SS "X Version Ranges"
499
An "x" in a version range specifies that the version number must start
500
with the supplied digits, but any digit may be used in place of the x\.
501
.
502
.P
503
The following are equivalent:
504
.
505
.IP "\(bu" 4
506
\fB"1\.2\.x" = ">=1\.2\.0 <1\.3\.0"\fR
507
.
508
.IP "\(bu" 4
509
\fB"1\.x\.x" = ">=1\.0\.0 <2\.0\.0"\fR
510
.
511
.IP "\(bu" 4
512
\fB"1\.2" = "1\.2\.x"\fR
513
.
514
.IP "\(bu" 4
515
\fB"1\.x" = "1\.x\.x"\fR
516
.
517
.IP "\(bu" 4
518
\fB"1" = "1\.x\.x"\fR
519
.
520
.IP "" 0
521
.
522
.P
523
You may not supply a comparator with a version containing an x\. Any
524
digits after the first "x" are ignored\.
525
.
526
.SS "URLs as Dependencies"
527
Starting with npm version 0\.2\.14, you may specify a tarball URL in place
528
of a version range\.
529
.
530
.P
531
This tarball will be downloaded and installed as a bundle at install
532
time\. See \fBnpm help bundle\fR
533
.
535
Packages/1\.0 says that you can have an "engines" field with an array of engine
536
names\. However, it has no provision for specifying which version of the engine
537
your stuff runs on\.
540
With npm, you can use either of the following styles to specify the version of
541
node that your stuff works on:
546
{ "engines" : [ "node >=0\.1\.27 <0\.1\.30" ] }
547
.
548
.fi
549
.
550
.IP "" 0
551
.
552
.P
553
or:
554
.
555
.IP "" 4
556
.
557
.nf
558
{ "engines" : { "node" : ">=0\.1\.27 <0\.1\.30" } }
559
.
560
.fi
561
.
562
.IP "" 0
563
.
564
.P
565
And, like with dependencies, if you don\'t specify the version (or if you
566
specify "*" as the version), then any version of node will do\.
569
If you specify an "engines" field, then npm will require that "node" be
570
somewhere on that list\. If "engines" is omitted, then npm will just assume
571
that it works on node\.