1 package.json(5) -- Specifics of npm's package.json handling
2 ===========================================================
6 This document is all you need to know about what's required in your package.json
7 file. It must be actual JSON, not just a JavaScript object literal.
9 A lot of the behavior described in this document is affected by the config
10 settings described in `npm-config(7)`.
14 npm will default some values based on package contents.
16 * `"scripts": {"start": "node server.js"}`
18 If there is a `server.js` file in the root of your package, then npm
19 will default the `start` command to `node server.js`.
21 * `"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}`
23 If there is a `wscript` file in the root of your package, npm will
24 default the `preinstall` command to compile using node-waf.
26 * `"scripts":{"preinstall": "node-gyp rebuild"}`
28 If there is a `binding.gyp` file in the root of your package, npm will
29 default the `preinstall` command to compile using node-gyp.
31 * `"contributors": [...]`
33 If there is an `AUTHORS` file in the root of your package, npm will
34 treat each line as a `Name <email> (url)` format, where email and url
35 are optional. Lines which start with a `#` or are blank, will be
40 The *most* important things in your package.json are the name and version fields.
41 Those are actually required, and your package won't install without
42 them. The name and version together form an identifier that is assumed
43 to be completely unique. Changes to the package should come along with
44 changes to the version.
46 The name is what your thing is called. Some tips:
48 * Don't put "js" or "node" in the name. It's assumed that it's js, since you're
49 writing a package.json file, and you can specify the engine using the "engines"
51 * The name ends up being part of a URL, an argument on the command line, and a
52 folder name. Any name with non-url-safe characters will be rejected.
53 Also, it can't start with a dot or an underscore.
54 * The name will probably be passed as an argument to require(), so it should
55 be something short, but also reasonably descriptive.
56 * You may want to check the npm registry to see if there's something by that name
57 already, before you get too attached to it. http://registry.npmjs.org/
61 The *most* important things in your package.json are the name and version fields.
62 Those are actually required, and your package won't install without
63 them. The name and version together form an identifier that is assumed
64 to be completely unique. Changes to the package should come along with
65 changes to the version.
67 Version must be parseable by
68 [node-semver](https://github.com/isaacs/node-semver), which is bundled
69 with npm as a dependency. (`npm install semver` to use it yourself.)
71 More on version numbers and ranges at semver(7).
75 Put a description in it. It's a string. This helps people discover your
76 package, as it's listed in `npm search`.
80 Put keywords in it. It's an array of strings. This helps people
81 discover your package as it's listed in `npm search`.
85 The url to the project homepage.
87 **NOTE**: This is *not* the same as "url". If you put a "url" field,
88 then the registry will think it's a redirection to your package that has
89 been published somewhere else, and spit at you.
91 Literally. Spit. I'm so not kidding.
95 The url to your project's issue tracker and / or the email address to which
96 issues should be reported. These are helpful for people who encounter issues
99 It should look like this:
101 { "url" : "http://github.com/owner/project/issues"
102 , "email" : "project@hostname.com"
105 You can specify either one or both values. If you want to provide only a url,
106 you can specify the value for "bugs" as a simple string instead of an object.
108 If a url is provided, it will be used by the `npm bugs` command.
112 You should specify a license for your package so that people know how they are
113 permitted to use it, and any restrictions you're placing on it.
115 The simplest way, assuming you're using a common license such as BSD or MIT, is
116 to just specify the name of the license you're using, like this:
118 { "license" : "BSD" }
120 If you have more complex licensing terms, or you want to provide more detail
121 in your package.json file, you can use the more verbose plural form, like this:
124 { "type" : "MyLicense"
125 , "url" : "http://github.com/owner/project/path/to/license"
129 It's also a good idea to include a license file at the top level in your package.
131 ## people fields: author, contributors
133 The "author" is one person. "contributors" is an array of people. A "person"
134 is an object with a "name" field and optionally "url" and "email", like this:
136 { "name" : "Barney Rubble"
137 , "email" : "b@rubble.com"
138 , "url" : "http://barnyrubble.tumblr.com/"
141 Or you can shorten that all into a single string, and npm will parse it for you:
143 "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)
145 Both email and url are optional either way.
147 npm also sets a top-level "maintainers" field with your npm user info.
151 The "files" field is an array of files to include in your project. If
152 you name a folder in the array, then it will also include the files
153 inside that folder. (Unless they would be ignored by another rule.)
155 You can also provide a ".npmignore" file in the root of your package,
156 which will keep files from being included, even if they would be picked
157 up by the files array. The ".npmignore" file works just like a
162 The main field is a module ID that is the primary entry point to your program.
163 That is, if your package is named `foo`, and a user installs it, and then does
164 `require("foo")`, then your main module's exports object will be returned.
166 This should be a module ID relative to the root of your package folder.
168 For most modules, it makes the most sense to have a main script and often not
173 A lot of packages have one or more executable files that they'd like to
174 install into the PATH. npm makes this pretty easy (in fact, it uses this
175 feature to install the "npm" executable.)
177 To use this, supply a `bin` field in your package.json which is a map of
178 command name to local file name. On install, npm will symlink that file into
179 `prefix/bin` for global installs, or `./node_modules/.bin/` for local
183 For example, npm has this:
185 { "bin" : { "npm" : "./cli.js" } }
187 So, when you install npm, it'll create a symlink from the `cli.js` script to
188 `/usr/local/bin/npm`.
190 If you have a single executable, and its name should be the name
191 of the package, then you can just supply it as a string. For example:
193 { "name": "my-program"
195 , "bin": "./path/to/program" }
197 would be the same as this:
199 { "name": "my-program"
201 , "bin" : { "my-program" : "./path/to/program" } }
205 Specify either a single file or an array of filenames to put in place for the
206 `man` program to find.
208 If only a single file is provided, then it's installed such that it is the
209 result from `man <pkgname>`, regardless of its actual filename. For example:
212 , "version" : "1.2.3"
213 , "description" : "A packaged foo fooer for fooing foos"
215 , "man" : "./man/doc.1"
218 would link the `./man/doc.1` file in such that it is the target for `man foo`
220 If the filename doesn't start with the package name, then it's prefixed.
224 , "version" : "1.2.3"
225 , "description" : "A packaged foo fooer for fooing foos"
227 , "man" : [ "./man/foo.1", "./man/bar.1" ]
230 will create files to do `man foo` and `man foo-bar`.
232 Man files must end with a number, and optionally a `.gz` suffix if they are
233 compressed. The number dictates which man section the file is installed into.
236 , "version" : "1.2.3"
237 , "description" : "A packaged foo fooer for fooing foos"
239 , "man" : [ "./man/foo.1", "./man/foo.2" ]
242 will create entries for `man foo` and `man 2 foo`
246 The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec details a
247 few ways that you can indicate the structure of your package using a `directories`
248 hash. If you look at [npm's package.json](http://registry.npmjs.org/npm/latest),
249 you'll see that it has directories for doc, lib, and man.
251 In the future, this information may be used in other creative ways.
255 Tell people where the bulk of your library is. Nothing special is done
256 with the lib folder in any way, but it's useful meta info.
260 If you specify a "bin" directory, then all the files in that folder will
261 be used as the "bin" hash.
263 If you have a "bin" hash already, then this has no effect.
267 A folder that is full of man pages. Sugar to generate a "man" array by
272 Put markdown files in here. Eventually, these will be displayed nicely,
275 ### directories.example
277 Put example scripts in here. Someday, it might be exposed in some clever way.
281 Specify the place where your code lives. This is helpful for people who
282 want to contribute. If the git repo is on github, then the `npm docs`
283 command will be able to find you.
289 , "url" : "http://github.com/isaacs/npm.git"
294 , "url" : "http://v8.googlecode.com/svn/trunk/"
297 The URL should be a publicly available (perhaps read-only) url that can be handed
298 directly to a VCS program without any modification. It should not be a url to an
299 html project page that you put in your browser. It's for computers.
303 The "scripts" member is an object hash of script commands that are run
304 at various times in the lifecycle of your package. The key is the lifecycle
305 event, and the value is the command to run at that point.
307 See `npm-scripts(7)` to find out more about writing package scripts.
311 A "config" hash can be used to set configuration
312 parameters used in package scripts that persist across upgrades. For
313 instance, if a package had the following:
316 , "config" : { "port" : "8080" } }
318 and then had a "start" command that then referenced the
319 `npm_package_config_port` environment variable, then the user could
320 override that by doing `npm config set foo:port 8001`.
322 See `npm-config(7)` and `npm-scripts(7)` for more on package
327 Dependencies are specified with a simple hash of package name to
328 version range. The version range is a string which has one or more
329 space-separated descriptors. Dependencies can also be identified with
330 a tarball or git URL.
332 **Please do not put test harnesses or transpilers in your
333 `dependencies` hash.** See `devDependencies`, below.
335 See semver(7) for more details about specifying version ranges.
337 * `version` Must match `version` exactly
338 * `>version` Must be greater than `version`
342 * `~version` "Approximately equivalent to version" See semver(7)
343 * `1.2.x` 1.2.0, 1.2.1, etc., but not 1.3.0
344 * `http://...` See 'URLs as Dependencies' below
345 * `*` Matches any version
346 * `""` (just an empty string) Same as `*`
347 * `version1 - version2` Same as `>=version1 <=version2`.
348 * `range1 || range2` Passes if either range1 or range2 are satisfied.
349 * `git...` See 'Git URLs as Dependencies' below
350 * `user/repo` See 'GitHub URLs' below
352 For example, these are all valid:
355 { "foo" : "1.0.0 - 2.9999.9999"
356 , "bar" : ">=1.0.2 <2.1.2"
357 , "baz" : ">1.0.2 <=2.3.4"
359 , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
360 , "asd" : "http://asdf.com/asdf.tar.gz"
368 ### URLs as Dependencies
370 You may specify a tarball URL in place of a version range.
372 This tarball will be downloaded and installed locally to your package at
375 ### Git URLs as Dependencies
377 Git urls can be of the form:
379 git://github.com/user/project.git#commit-ish
380 git+ssh://user@hostname:project.git#commit-ish
381 git+ssh://user@hostname/project.git#commit-ish
382 git+http://user@hostname/project/blah.git#commit-ish
383 git+https://user@hostname/project/blah.git#commit-ish
385 The `commit-ish` can be any tag, sha, or branch which can be supplied as
386 an argument to `git checkout`. The default is `master`.
390 As of version 1.1.65, you can refer to GitHub urls as just "foo": "user/foo-project". For example:
397 "express": "visionmedia/express"
404 If someone is planning on downloading and using your module in their
405 program, then they probably don't want or need to download and build
406 the external test or documentation framework that you use.
408 In this case, it's best to list these additional items in a
409 `devDependencies` hash.
411 These things will be installed when doing `npm link` or `npm install`
412 from the root of a package, and can be managed like any other npm
413 configuration param. See `npm-config(7)` for more on the topic.
415 For build steps that are not platform-specific, such as compiling
416 CoffeeScript or other languages to JavaScript, use the `prepublish`
417 script to do this, and make the required package a devDependency.
422 { "name": "ethopia-waza",
423 "description": "a delightfully fruity coffee varietal",
426 "coffee-script": "~1.6.3"
429 "prepublish": "coffee -o lib/ -c src/waza.coffee"
431 "main": "lib/waza.js"
435 The `prepublish` script will be run before publishing, so that users
436 can consume the functionality without requiring them to compile it
437 themselves. In dev mode (ie, locally running `npm install`), it'll
438 run this script as well, so that you can test it easily.
440 ## bundledDependencies
442 Array of package names that will be bundled when publishing the package.
444 If this is spelled `"bundleDependencies"`, then that is also honorable.
446 ## optionalDependencies
448 If a dependency can be used, but you would like npm to proceed if it
449 cannot be found or fails to install, then you may put it in the
450 `optionalDependencies` hash. This is a map of package name to version
451 or url, just like the `dependencies` hash. The difference is that
452 failure is tolerated.
454 It is still your program's responsibility to handle the lack of the
455 dependency. For example, something like this:
458 var foo = require('foo')
459 var fooVersion = require('foo/package.json').version
463 if ( notGoodFooVersion(fooVersion) ) {
467 // .. then later in your program ..
473 Entries in `optionalDependencies` will override entries of the same name in
474 `dependencies`, so it's usually best to only put in one place.
478 You can specify the version of node that your stuff works on:
480 { "engines" : { "node" : ">=0.10.3 <0.12" } }
482 And, like with dependencies, if you don't specify the version (or if you
483 specify "\*" as the version), then any version of node will do.
485 If you specify an "engines" field, then npm will require that "node" be
486 somewhere on that list. If "engines" is omitted, then npm will just assume
487 that it works on node.
489 You can also use the "engines" field to specify which versions of npm
490 are capable of properly installing your program. For example:
492 { "engines" : { "npm" : "~1.0.20" } }
494 Note that, unless the user has set the `engine-strict` config flag, this
495 field is advisory only.
499 If you are sure that your module will *definitely not* run properly on
500 versions of Node/npm other than those specified in the `engines` hash,
501 then you can set `"engineStrict": true` in your package.json file.
502 This will override the user's `engine-strict` config setting.
504 Please do not do this unless you are really very very sure. If your
505 engines hash is something overly restrictive, you can quite easily and
506 inadvertently lock yourself into obscurity and prevent your users from
507 updating to new versions of Node. Consider this choice carefully. If
508 people abuse it, it will be removed in a future version of npm.
512 You can specify which operating systems your
515 "os" : [ "darwin", "linux" ]
517 You can also blacklist instead of whitelist operating systems,
518 just prepend the blacklisted os with a '!':
522 The host operating system is determined by `process.platform`
524 It is allowed to both blacklist, and whitelist, although there isn't any
525 good reason to do this.
529 If your code only runs on certain cpu architectures,
530 you can specify which ones.
532 "cpu" : [ "x64", "ia32" ]
534 Like the `os` option, you can also blacklist architectures:
536 "cpu" : [ "!arm", "!mips" ]
538 The host architecture is determined by `process.arch`
542 If your package is primarily a command-line application that should be
543 installed globally, then set this value to `true` to provide a warning
544 if it is installed locally.
546 It doesn't actually prevent users from installing it locally, but it
547 does help prevent some confusion if it doesn't work as expected.
551 If you set `"private": true` in your package.json, then npm will refuse
554 This is a way to prevent accidental publication of private repositories.
555 If you would like to ensure that a given package is only ever published
556 to a specific registry (for example, an internal registry),
557 then use the `publishConfig` hash described below
558 to override the `registry` config param at publish-time.
562 This is a set of config values that will be used at publish-time. It's
563 especially handy if you want to set the tag or registry, so that you can
564 ensure that a given package is not tagged with "latest" or published to
565 the global public registry by default.
567 Any config values can be overridden, but of course only "tag" and
568 "registry" probably matter for the purposes of publishing.
570 See `npm-config(7)` to see the list of config options that can be