Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 651 lines (650 sloc) 16.477 kb
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
1 .\" Generated with Ronnjs/v0.1
2 .\" http://github.com/kapouer/ronnjs/
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
3 .
39985c8 isaacs make doc
isaacs authored
4 .TH "NPM\-JSON" "1" "January 2011" "" ""
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
5 .
6 .SH "NAME"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
7 \fBnpm-json\fR \-\- Specifics of npm\'s package\.json handling
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
8 .
9 .SH "DESCRIPTION"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
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\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
13 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
14 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
15 This document is all you need to know about what\'s required in your package\.json
16 file\.
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
17 .
c1cc130 isaacs make doc
isaacs authored
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 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
22 .SH "name"
23 The \fImost\fR important things in your package\.json are the name and version fields\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
24 .
25 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
26 The name is what your thing is called\. Some tips:
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
27 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
28 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
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\.)
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
32 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
33 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
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\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
37 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
38 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
39 The name will probably be passed as an argument to require(), so it should
40 be something short, but also reasonably descriptive\.
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
41 .
42 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
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/
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
45 .
46 .IP "" 0
47 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
48 .SH "version"
49 The \fImost\fR important things in your package\.json are the name and version fields\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
50 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
51 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
52 Version must be semver \fIhttp://semver\.org\fR\-compliant\. npm assumes that you\'ve
53 read the semver page, and that you comply with it\. Here\'s how it deviates from
54 what\'s on semver\.org:
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
55 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
56 .IP "\(bu" 4
57 Versions can start with "v"
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
58 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
59 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
60 A numeric item separated from the main three\-number version by a hyphen
61 will be interpreted as a "build" number, and will \fIincrease\fR the version\.
62 But, if the tag is not a number separated by a hyphen, then it\'s treated
63 as a pre\-release tag, and is \fIless than\fR the version without a tag\.
64 So, 0\.1\.2\-7 > 0\.1\.2\-6 > 0\.1\.2 > 0\.1\.2beta
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
65 .
66 .IP "" 0
67 .
68 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
69 This is a little bit confusing to explain, but matches what you see in practice
70 when people create tags in git like "v1\.2\.3" and then do "git describe" to generate
71 a patch version\. (This is how node\'s versions are generated, and has driven this
72 design\.)
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
73 .
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
74 .SH "description"
648c9ff isaacs Doc json field enhancements
isaacs authored
75 Put a description in it\. It\'s a string\. This helps people discover your
76 package, as it\'s listed in \fBnpm ls\fR\|\.
77 .
78 .SH "keywords"
79 Put keywords in it\. It\'s an array of strings\. This helps people
80 discover your package as it\'s listed in \fBnpm ls\fR\|\.
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
81 .
82 .SH "homepage"
83 The url to the project homepage\.
84 .
648c9ff isaacs Doc json field enhancements
isaacs authored
85 .P
86 \fBNOTE\fR: This is \fInot\fR the same as "url"\. If you put a "url" field,
87 then the registry will think it\'s a redirection to your package that has
88 been published somewhere else, and spit at you\.
89 .
90 .P
91 Literally\. Spit\. I\'m so not kidding\.
92 .
085fbd4 isaacs Update json documentation
isaacs authored
93 .SH "people fields: author, contributors"
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
94 The "author" is one person\. "contributors" is an array of people\. A "person"
95 is an object with a "name" field and optionally "url" and "email", like this:
96 .
97 .IP "" 4
98 .
99 .nf
100 { "name" : "Barney Rubble"
101 , "email" : "b@rubble\.com"
102 , "url" : "http://barnyrubble\.tumblr\.com/"
103 }
104 .
105 .fi
106 .
107 .IP "" 0
108 .
109 .P
110 Or you can shorten that all into a single string, and npm will parse it for you:
111 .
112 .IP "" 4
113 .
114 .nf
115 "Barney Rubble <b@rubble\.com> (http://barnyrubble\.tumblr\.com/)
116 .
117 .fi
118 .
119 .IP "" 0
120 .
121 .P
122 Both email and url are optional either way\.
123 .
124 .P
125 npm also sets a top\-level "maintainers" field with your npm user info\.
126 .
39985c8 isaacs make doc
isaacs authored
127 .SH "files"
128 The "files" field is an array of files to include in your project\. If
129 you name a folder in the array, then it will also include the files
130 inside that folder\. The default is just \fB[""]\fR which includes the
131 entire package folder in the tarball, but you may want to only include
132 specific things\.
133 .
134 .P
135 If you specify modules, bins, or man pages, then those will be
136 automatically added to the files array, even if they would not
137 ordinarily be included\.
138 .
139 .P
140 You can also provide a "\.npmignore" file in the root of your package,
141 which will keep files from being included, even if they would be picked
142 up by the files array\.
143 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
144 .SH "main"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
145 The main field is a module ID that is the primary entry point to your program\.
146 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\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
147 .
148 .P
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
149 This should be a module ID relative to the root of your package folder\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
150 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
151 .P
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
152 For most modules, it makes the most sense to have a main script and often not
153 much else\.
154 .
155 .SH "bin"
156 A lot of packages have one or more executable files that they\'d like to
157 install into the PATH\. npm makes this pretty easy (in fact, it uses this
158 feature to install the "npm" executable\.)
159 .
160 .P
161 To use this, supply a \fBbin\fR field in your package\.json which is a map of
162 command name to local file name\. On install, npm will link that file into
163 place right next to wherever node is installed\. (Presumably, this is in your
164 PATH, and defaults to \fB/usr/local/bin\fR\|\.) On activation, the versioned file
165 will get linked to the main filename (just like how the main\.js stuff works,
166 but with an executable in the PATH\.)
167 .
168 .P
169 For example, npm has this:
170 .
171 .IP "" 4
172 .
173 .nf
174 { "bin" : { "npm" : "\./cli\.js" } }
175 .
176 .fi
177 .
178 .IP "" 0
179 .
180 .P
181 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
182 create a symlink from \fB/usr/local/bin/npm\-version\fR to \fB/usr/local/bin/npm\fR\|\.
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
183 .
085fbd4 isaacs Update json documentation
isaacs authored
184 .P
19206ee Whyme Lyu Document require.main doesn't work as usual in bin file.
5long authored
185 Notice that if the executable file is interpreted by node (i\.e\., specifying
186 node in the shebang line), npm actually installs a shim instead of symlinking
187 it, which causes expressions \fBrequire\.main === module\fR and \fBmodule\.id === "\."\fR
188 evaluate to \fBfalse\fR within the file\. This seems unable to be resolved until
189 node provides a "flexible \fBrequire()\fR"\.
190 .
191 .P
085fbd4 isaacs Update json documentation
isaacs authored
192 Shortcut: If you have a single executable, and its name is already what you
193 want it to be, then you can just supply it as a string\. For example:
194 .
195 .IP "" 4
196 .
197 .nf
198 { "bin" : "\./path/to/program" }
199 .
200 .fi
201 .
202 .IP "" 0
203 .
204 .P
205 would be the same as this:
206 .
207 .IP "" 4
208 .
209 .nf
210 { "bin" : { "program" : "\./path/to/program" } }
211 .
212 .fi
213 .
214 .IP "" 0
215 .
c5288e3 isaacs make doc
isaacs authored
216 .SH "modules"
217 The "modules" member exposes CommonJS modules in the package\. So, if you had a
218 package named \fBfoo\fR, and the package\.json contains \fB"modules":{"bar":"\./lib/baz"}\fR,
219 and there was a file called \fB\|\./lib/baz\.js\fR, then require("foo/bar") would include
220 the module defined in \fB\|\./lib/baz\.js\fR\|\.
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
221 .
222 .P
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
223 Subfolders are supported, so you can do this:
224 .
225 .IP "" 4
226 .
227 .nf
228 { "name" : "foo"
229 , "modules" :
230 { "bar/baz" : "\./lib/bar/baz"
231 , "quux" : "\./quux"
232 }
233 }
234 .
235 .fi
236 .
237 .IP "" 0
238 .
239 .P
240 And then, doing \fBrequire("foo/bar/baz")\fR would return the module at \fB\|\./lib/bar/baz\fR
085fbd4 isaacs Update json documentation
isaacs authored
241 in the foo package\. Doing \fBrequire("foo/quux")\fR would return the module at \fB\|\./quux\fR in the foo package\.
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
242 .
243 .P
c5288e3 isaacs make doc
isaacs authored
244 Just like the \fBmain\fR script, the modules linked in this fashion will have their
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
245 dependencies and paths set up properly by npm\. (In fact, "main" is just sugar
246 around setting a module named "index"\.)
247 .
c1cc130 isaacs make doc
isaacs authored
248 .SH "man"
249 Specify either a single file or an array of filenames to put in place for the \fBman\fR program to find\.
250 .
251 .P
252 If only a single file is provided, then it\'s installed such that it is the
253 result from \fBman <pkgname>\fR, regardless of its actual filename\. For example:
254 .
255 .IP "" 4
256 .
257 .nf
258 { "name" : "foo"
259 , "man" : "\./man/doc\.1"
260 }
261 .
262 .fi
263 .
264 .IP "" 0
265 .
266 .P
267 would link the \fB\|\./man/doc\.1\fR file in such that it is the target for \fBman foo\fR
268 .
269 .P
270 If the filename doesn\'t start with the package name, then it\'s prefixed\.
271 So, this:
272 .
273 .IP "" 4
274 .
275 .nf
276 { "name" : "foo"
277 , "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
278 }
279 .
280 .fi
281 .
282 .IP "" 0
283 .
284 .P
285 will create files to do \fBman foo\fR and \fBman foo\-bar\fR\|\.
286 .
287 .P
288 Man files must end with a number, and optionally a \fB\|\.gz\fR suffix if they are
289 compressed\. The number dictates which man section the file is installed into\.
290 .
291 .IP "" 4
292 .
293 .nf
294 { "name" : "foo"
295 , "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
296 }
297 .
298 .fi
299 .
300 .IP "" 0
301 .
302 .P
303 will create entries for \fBman foo\fR and \fBman 2 foo\fR
304 .
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
305 .SH "directories"
306 The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
307 few ways that you can indicate the structure of your package using a \fBdirectories\fR
308 hash\. If you look at npm\'s package\.json \fIhttp://registry\.npmjs\.org/npm/latest\fR,
309 you\'ll see that it has directories for doc, lib, and man\.
310 .
311 .P
312 In the future, this information may be used in other creative ways\.
313 .
314 .SS "directories\.lib"
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
315 If you specify a "lib" directory, and do not supply a modules hash, then the lib
316 folder will be walked and any \fI\|\.js or \fR\|\.node files found will be exposed as a
c1cc130 isaacs make doc
isaacs authored
317 default module hash\.
e4f1f57 isaacs move some stuff around, add various meta things that are nice
isaacs authored
318 .
319 .P
320 Providing an explicit modules hash is encouraged over exposing the entire lib
321 folder\.
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
322 .
c1cc130 isaacs make doc
isaacs authored
323 .SS "directories\.bin"
324 If you specify a "bin" directory, then all the files in that folder will be used
325 as the "bin" hash\.
326 .
327 .P
328 If you have a "bin" hash already, then this has no effect\.
329 .
8299e4f isaacs Add info about a few directories that are relevant
isaacs authored
330 .SS "directories\.man"
331 A folder that is full of man pages\. Sugar to generate a "man" array by walking the folder\.
332 .
333 .SS "directories\.doc"
334 Put markdown files in here\. Eventually, these will be displayed nicely, maybe, someday\.
335 .
336 .SS "directories\.example"
337 Put example scripts in here\. Someday, it might be exposed in some clever way\.
338 .
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
339 .SH "repository"
340 Specify the place where your code lives\. This is helpful for people who want to
341 contribute, as well as perhaps maybe being the underpinning of some magical "track
342 this package on git" feature someday maybe if somebody wants to write it ever\.
343 .
344 .P
345 Do it like this:
346 .
347 .IP "" 4
348 .
349 .nf
350 "repository" :
351 { "type" : "git"
352 , "url" : "http://github\.com/isaacs/npm\.git"
353 }
354 "repository" :
355 { "type" : "svn"
356 , "url" : "http://v8\.googlecode\.com/svn/trunk/"
357 }
358 .
359 .fi
360 .
361 .IP "" 0
362 .
363 .P
364 The URL should be a publicly available (perhaps read\-only) url that can be handed
365 directly to a VCS program without any modification\. It should not be a url to an
366 html project page that you put in your browser\. It\'s for computers\.
367 .
368 .P
369 Here are some examples of Doing It Wrong:
370 .
371 .IP "" 4
372 .
373 .nf
374 WRONG!
375 "repository" :
376 { "type" : "git"
377 , "url" : "git@github\.com:isaacs/npm\.git" <\-\- THIS IS PRIVATE!
378 }
379 ALSO WRONG!
380 "repository" :
381 { "type" : "git"
382 , "url" : "http://github\.com/isaacs/npm" <\-\- THIS IS WEBPAGE!
383 }
085fbd4 isaacs Update json documentation
isaacs authored
384 This is ok, but completely unnecessary:
385 "repository" :
386 { "type" : "git"
387 , "url" : "http://github\.com/isaacs/npm\.git"
388 , "private" : "git@github\.com:isaacs/npm\.git"
389 , "web" : "http://github\.com/isaacs/npm"
390 }
4792d40 isaacs Put directories.lib info back in the doc, and document the repository se...
isaacs authored
391 .
392 .fi
393 .
394 .IP "" 0
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
395 .
396 .SH "scripts"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
397 The "scripts" member is an object hash of script commands that are run
398 at various times in the lifecycle of your package\. The key is the lifecycle
399 event, and the value is the command to run at that point\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
400 .
401 .P
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
402 See \fBnpm help scripts\fR to find out more about writing package scripts\.
403 .
39985c8 isaacs make doc
isaacs authored
404 .SH "config"
405 A "config" hash can be used to set configuration
406 parameters used in package scripts that persist across upgrades\. For
407 instance, if a package had the following:
408 .
409 .IP "" 4
410 .
411 .nf
412 { "name" : "foo"
413 , "config" : { "port" : "8080" } }
414 .
415 .fi
416 .
417 .IP "" 0
418 .
419 .P
420 and then had a "start" command that then referenced the \fBnpm_package_config_port\fR environment variable, then the user could
421 override that by doing \fBnpm config set foo:port 8001\fR\|\.
422 .
423 .P
424 See \fBnpm help config\fR and \fBnpm help scripts\fR for more on package
425 configs\.
426 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
427 .SH "dependencies"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
428 Dependencies are specified with a simple hash of package name to version
429 range\. The version range is EITHER a string with has one or more
430 space\-separated descriptors, OR a range like "fromVersion \- toVersion"
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
431 .
432 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
433 Version range descriptors may be any of the following styles, where "version"
434 is a semver compatible version identifier\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
435 .
436 .IP "\(bu" 4
437 \fBversion\fR Must match \fBversion\fR exactly
438 .
439 .IP "\(bu" 4
440 \fB=version\fR Same as just \fBversion\fR
441 .
442 .IP "\(bu" 4
443 \fB>version\fR Must be greater than \fBversion\fR
444 .
445 .IP "\(bu" 4
446 \fB>=version\fR etc
447 .
448 .IP "\(bu" 4
449 \fB<version\fR
450 .
451 .IP "\(bu" 4
452 \fB<=version\fR
453 .
454 .IP "\(bu" 4
d64bdba isaacs make doc
isaacs authored
455 \fB~version\fR See \'Tilde Version Ranges\' below
456 .
457 .IP "\(bu" 4
458 \fB1\.2\.x\fR See \'X Version Ranges\' below
459 .
460 .IP "\(bu" 4
461 \fBhttp://\.\.\.\fR See \'URLs as Dependencies\' below
462 .
463 .IP "\(bu" 4
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
464 \fB*\fR Matches any version
465 .
466 .IP "\(bu" 4
467 \fB""\fR (just an empty string) Same as \fB*\fR
468 .
469 .IP "\(bu" 4
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
470 \fBversion1 \- version2\fR Same as \fB>=version1 <=version2\fR\|\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
471 .
49b7bf0 isaacs Document the || in version ranges.
isaacs authored
472 .IP "\(bu" 4
473 \fBrange1 || range2\fR Passes if either range1 or range2 are satisfied\.
474 .
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
475 .IP "" 0
476 .
477 .P
478 For example, these are all valid:
479 .
480 .IP "" 4
481 .
482 .nf
483 { "dependencies" :
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
484 { "foo" : "1\.0\.0 \- 2\.9999\.9999"
485 , "bar" : ">=1\.0\.2 <2\.1\.2"
486 , "baz" : ">1\.0\.2 <=2\.3\.4"
487 , "boo" : "2\.0\.1"
49b7bf0 isaacs Document the || in version ranges.
isaacs authored
488 , "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
d64bdba isaacs make doc
isaacs authored
489 , "asd" : "http://asdf\.com/asdf\.tar\.gz"
490 , "til" : "~1\.2"
491 , "elf" : "~1\.2\.3"
492 , "two" : "2\.x"
493 , "thr" : "3\.3\.x"
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
494 }
495 }
496 .
497 .fi
498 .
499 .IP "" 0
500 .
d64bdba isaacs make doc
isaacs authored
501 .SS "Tilde Version Ranges"
502 A range specifier starting with a tilde \fB~\fR character is matched against
503 a version in the following fashion\.
504 .
505 .IP "\(bu" 4
506 The version must be at least as high as the range\.
507 .
508 .IP "\(bu" 4
509 The version must be less than the next major revision above the range\.
510 .
511 .IP "" 0
512 .
513 .P
514 For example, the following are equivalent:
515 .
516 .IP "\(bu" 4
517 \fB"~1\.2\.3" = ">=1\.2\.3 <1\.3\.0"\fR
518 .
519 .IP "\(bu" 4
520 \fB"~1\.2" = ">=1\.2\.0 <2\.0\.0"\fR
521 .
522 .IP "\(bu" 4
523 \fB"~1" = ">=1\.0\.0 <2\.0\.0"\fR
524 .
525 .IP "" 0
526 .
527 .SS "X Version Ranges"
528 An "x" in a version range specifies that the version number must start
529 with the supplied digits, but any digit may be used in place of the x\.
530 .
531 .P
532 The following are equivalent:
533 .
534 .IP "\(bu" 4
535 \fB"1\.2\.x" = ">=1\.2\.0 <1\.3\.0"\fR
536 .
537 .IP "\(bu" 4
538 \fB"1\.x\.x" = ">=1\.0\.0 <2\.0\.0"\fR
539 .
540 .IP "\(bu" 4
541 \fB"1\.2" = "1\.2\.x"\fR
542 .
543 .IP "\(bu" 4
544 \fB"1\.x" = "1\.x\.x"\fR
545 .
546 .IP "\(bu" 4
547 \fB"1" = "1\.x\.x"\fR
548 .
549 .IP "" 0
550 .
551 .P
552 You may not supply a comparator with a version containing an x\. Any
553 digits after the first "x" are ignored\.
554 .
555 .SS "URLs as Dependencies"
556 Starting with npm version 0\.2\.14, you may specify a tarball URL in place
557 of a version range\.
558 .
559 .P
560 This tarball will be downloaded and installed as a bundle at install
561 time\. See \fBnpm help bundle\fR
562 .
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
563 .SH "engines"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
564 Packages/1\.0 says that you can have an "engines" field with an array of engine
565 names\. However, it has no provision for specifying which version of the engine
566 your stuff runs on\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
567 .
568 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
569 With npm, you can use either of the following styles to specify the version of
570 node that your stuff works on:
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
571 .
572 .IP "" 4
573 .
574 .nf
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
575 { "engines" : [ "node >=0\.1\.27 <0\.1\.30" ] }
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
576 .
577 .fi
578 .
579 .IP "" 0
580 .
581 .P
582 or:
583 .
584 .IP "" 4
585 .
586 .nf
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
587 { "engines" : { "node" : ">=0\.1\.27 <0\.1\.30" } }
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
588 .
589 .fi
590 .
591 .IP "" 0
592 .
593 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
594 And, like with dependencies, if you don\'t specify the version (or if you
595 specify "*" as the version), then any version of node will do\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
596 .
597 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
598 If you specify an "engines" field, then npm will require that "node" be
599 somewhere on that list\. If "engines" is omitted, then npm will just assume
600 that it works on node\.
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
601 .
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
602 .SH "overlay"
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
603 npm responds to the \fBnode\fR and \fBnpm\fR env\-specific package\.json values, which
604 you can hang on the "overlay" key\.
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
605 .
606 .P
607 For example:
608 .
609 .IP "" 4
610 .
611 .nf
612 { "name" : "foo"
613 , "version" : 7
614 , "description" : "generic description"
615 , "overlay" :
616 { "node" :
617 { "name" : "bar"
618 , "description" : "description for node"
619 }
620 , "npm" :
621 { "version" : "1\.0\.7"
622 , "description" : "description for npm"
623 }
624 , "narwhal" :
625 { "description" : "description for narwhal" }
626 }
627 }
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
628 .
629 .fi
630 .
631 .IP "" 0
632 .
633 .P
da9eb9a isaacs Update json docs to be more comprehensive. Fix #45
isaacs authored
634 In this case, this is what npm will treat it as:
635 .
636 .IP "" 4
637 .
638 .nf
639 { "name" : "bar"
640 , "version" : "1\.0\.7"
641 , "description" : "description for npm"
642 }
643 .
644 .fi
645 .
646 .IP "" 0
b70b2a0 isaacs Add built documentation to project, so that the install doesn't require ...
isaacs authored
647 .
648 .P
f2ccd17 isaacs Use ronnjs instead of the ronn rubygem to build docs
isaacs authored
649 This way, even if npm is not exactly the same as some other package management
650 system, you can still use both, and it can be a happy planet\.
Something went wrong with that request. Please try again.