1 .TH "PACKAGE\.JSON" "5" "September 2015" "" ""
3 \fBpackage.json\fR \- Specifics of npm's package\.json handling
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 help 7 \fBnpm\-config\fP\|\.
13 The \fImost\fR important things in your package\.json are the name and version fields\.
14 Those are actually required, and your package won't install without
15 them\. The name and version together form an identifier that is assumed
16 to be completely unique\. Changes to the package should come along with
17 changes to the version\.
19 The name is what your thing is called\.
24 The name must be shorter than 214 characters\. This includes the scope for
27 The name can't start with a dot or an underscore\.
29 New packages must not have uppercase letters in the name\.
31 The name ends up being part of a URL, an argument on the command line, and a
32 folder name\. Therefore, the name can't contain any non\-URL\-safe characters\.
39 Don't use the same name as a core Node module\.
41 Don't put "js" or "node" in the name\. It's assumed that it's js, since you're
42 writing a package\.json file, and you can specify the engine using the "engines"
45 The name will probably be passed as an argument to require(), so it should
46 be something short, but also reasonably descriptive\.
48 You may want to check the npm registry to see if there's something by that name
49 already, before you get too attached to it\. https://www\.npmjs\.com/
53 A name can be optionally prefixed by a scope, e\.g\. \fB@myorg/mypackage\fP\|\. See
54 npm help 7 \fBnpm\-scope\fP for more detail\.
57 The \fImost\fR important things in your package\.json are the name and version fields\.
58 Those are actually required, and your package won't install without
59 them\. The name and version together form an identifier that is assumed
60 to be completely unique\. Changes to the package should come along with
61 changes to the version\.
63 Version must be parseable by
64 node\-semver \fIhttps://github\.com/isaacs/node\-semver\fR, which is bundled
65 with npm as a dependency\. (\fBnpm install semver\fP to use it yourself\.)
67 More on version numbers and ranges at npm help 7 semver\.
70 Put a description in it\. It's a string\. This helps people discover your
71 package, as it's listed in \fBnpm search\fP\|\.
74 Put keywords in it\. It's an array of strings\. This helps people
75 discover your package as it's listed in \fBnpm search\fP\|\.
78 The url to the project homepage\.
80 \fBNOTE\fR: This is \fInot\fR the same as "url"\. If you put a "url" field,
81 then the registry will think it's a redirection to your package that has
82 been published somewhere else, and spit at you\.
84 Literally\. Spit\. I'm so not kidding\.
87 The url to your project's issue tracker and / or the email address to which
88 issues should be reported\. These are helpful for people who encounter issues
91 It should look like this:
95 { "url" : "https://github\.com/owner/project/issues"
96 , "email" : "project@hostname\.com"
101 You can specify either one or both values\. If you want to provide only a url,
102 you can specify the value for "bugs" as a simple string instead of an object\.
104 If a url is provided, it will be used by the \fBnpm bugs\fP command\.
107 You should specify a license for your package so that people know how they are
108 permitted to use it, and any restrictions you're placing on it\.
110 If you're using a common license such as BSD\-2\-Clause or MIT, add a
111 current SPDX license identifier for the license you're using, like this:
115 { "license" : "BSD\-3\-Clause" }
119 You can check the full list of SPDX license IDs \fIhttps://spdx\.org/licenses/\fR\|\.
120 Ideally you should pick one that is
121 OSI \fIhttp://opensource\.org/licenses/alphabetical\fR approved\.
123 If your package is licensed under multiple common licenses, use an SPDX license
124 expression syntax version 2\.0 string \fIhttp://npmjs\.com/package/spdx\fR, like this:
128 { "license" : "(ISC OR GPL\-3\.0)" }
132 If you are using a license that hasn't been assigned an SPDX identifier, or if
133 you are using a custom license, use the following valid SPDX expression:
137 { "license" : "SEE LICENSE IN <filename>" }
141 Then include a file named \fB<filename>\fP at the top level of the package\.
143 Some old packages used license objects or a "licenses" property containing an
144 array of license objects:
148 // Not valid metadata
151 , "url" : "http://opensource\.org/licenses/ISC"
155 // Not valid metadata
159 , "url": "http://www\.opensource\.org/licenses/mit\-license\.php"
161 , { "type": "Apache\-2\.0"
162 , "url": "http://opensource\.org/licenses/apache2\.0\.php"
169 Those styles are now deprecated\. Instead, use SPDX expressions, like this:
175 { "license": "(MIT OR Apache\-2\.0)" }
179 Finally, if you do not wish to grant others the right to use a private or
180 unpublished package under any terms:
184 { "license": "UNLICENSED"}
188 Consider also setting \fB"private": true\fP to prevent accidental publication\.
189 .SH people fields: author, contributors
191 The "author" is one person\. "contributors" is an array of people\. A "person"
192 is an object with a "name" field and optionally "url" and "email", like this:
196 { "name" : "Barney Rubble"
197 , "email" : "b@rubble\.com"
198 , "url" : "http://barnyrubble\.tumblr\.com/"
203 Or you can shorten that all into a single string, and npm will parse it for you:
207 "Barney Rubble <b@rubble\.com> (http://barnyrubble\.tumblr\.com/)"
211 Both email and url are optional either way\.
213 npm also sets a top\-level "maintainers" field with your npm user info\.
216 The "files" field is an array of files to include in your project\. If
217 you name a folder in the array, then it will also include the files
218 inside that folder\. (Unless they would be ignored by another rule\.)
220 You can also provide a "\.npmignore" file in the root of your package or
221 in subdirectories, which will keep files from being included, even
222 if they would be picked up by the files array\. The \fB\|\.npmignore\fP file
223 works just like a \fB\|\.gitignore\fP\|\.
225 Certain files are always included, regardless of settings:
230 \fBREADME\fP (and its variants)
232 \fBCHANGELOG\fP (and its variants)
234 \fBLICENSE\fP / \fBLICENCE\fP
238 Conversely, some files are always ignored:
249 \fB\|\.lock\-wscript\fP
251 \fB\|\.wafpickle\-N\fP
259 \fBnpm\-debug\.log\fP
264 The main field is a module ID that is the primary entry point to your program\.
265 That is, if your package is named \fBfoo\fP, and a user installs it, and then does
266 \fBrequire("foo")\fP, then your main module's exports object will be returned\.
268 This should be a module ID relative to the root of your package folder\.
270 For most modules, it makes the most sense to have a main script and often not
274 A lot of packages have one or more executable files that they'd like to
275 install into the PATH\. npm makes this pretty easy (in fact, it uses this
276 feature to install the "npm" executable\.)
278 To use this, supply a \fBbin\fP field in your package\.json which is a map of
279 command name to local file name\. On install, npm will symlink that file into
280 \fBprefix/bin\fP for global installs, or \fB\|\./node_modules/\.bin/\fP for local
283 For example, myapp could have this:
287 { "bin" : { "myapp" : "\./cli\.js" } }
291 So, when you install myapp, it'll create a symlink from the \fBcli\.js\fP script to
292 \fB/usr/local/bin/myapp\fP\|\.
294 If you have a single executable, and its name should be the name
295 of the package, then you can just supply it as a string\. For example:
299 { "name": "my\-program"
300 , "version": "1\.2\.5"
301 , "bin": "\./path/to/program" }
305 would be the same as this:
309 { "name": "my\-program"
310 , "version": "1\.2\.5"
311 , "bin" : { "my\-program" : "\./path/to/program" } }
316 Specify either a single file or an array of filenames to put in place for the
317 \fBman\fP program to find\.
319 If only a single file is provided, then it's installed such that it is the
320 result from \fBman <pkgname>\fP, regardless of its actual filename\. For example:
325 , "version" : "1\.2\.3"
326 , "description" : "A packaged foo fooer for fooing foos"
328 , "man" : "\./man/doc\.1"
333 would link the \fB\|\./man/doc\.1\fP file in such that it is the target for \fBman foo\fP
335 If the filename doesn't start with the package name, then it's prefixed\.
341 , "version" : "1\.2\.3"
342 , "description" : "A packaged foo fooer for fooing foos"
344 , "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
349 will create files to do \fBman foo\fP and \fBman foo\-bar\fP\|\.
351 Man files must end with a number, and optionally a \fB\|\.gz\fP suffix if they are
352 compressed\. The number dictates which man section the file is installed into\.
357 , "version" : "1\.2\.3"
358 , "description" : "A packaged foo fooer for fooing foos"
360 , "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
365 will create entries for \fBman foo\fP and \fBman 2 foo\fP
368 The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
369 few ways that you can indicate the structure of your package using a \fBdirectories\fP
370 object\. If you look at npm's package\.json \fIhttps://registry\.npmjs\.org/npm/latest\fR,
371 you'll see that it has directories for doc, lib, and man\.
373 In the future, this information may be used in other creative ways\.
376 Tell people where the bulk of your library is\. Nothing special is done
377 with the lib folder in any way, but it's useful meta info\.
380 If you specify a \fBbin\fP directory in \fBdirectories\.bin\fP, all the files in
381 that folder will be added\.
383 Because of the way the \fBbin\fP directive works, specifying both a
384 \fBbin\fP path and setting \fBdirectories\.bin\fP is an error\. If you want to
385 specify individual files, use \fBbin\fP, and for all the files in an
386 existing \fBbin\fP directory, use \fBdirectories\.bin\fP\|\.
389 A folder that is full of man pages\. Sugar to generate a "man" array by
393 Put markdown files in here\. Eventually, these will be displayed nicely,
395 .SS directories\.example
397 Put example scripts in here\. Someday, it might be exposed in some clever way\.
400 Specify the place where your code lives\. This is helpful for people who
401 want to contribute\. If the git repo is on GitHub, then the \fBnpm docs\fP
402 command will be able to find you\.
410 , "url" : "https://github\.com/npm/npm\.git"
415 , "url" : "https://v8\.googlecode\.com/svn/trunk/"
420 The URL should be a publicly available (perhaps read\-only) url that can be handed
421 directly to a VCS program without any modification\. It should not be a url to an
422 html project page that you put in your browser\. It's for computers\.
424 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
425 shortcut syntax you use for \fBnpm install\fP:
429 "repository": "npm/npm"
431 "repository": "gist:11081aaa281"
433 "repository": "bitbucket:example/repo"
435 "repository": "gitlab:another/repo"
440 The "scripts" property is a dictionary containing script commands that are run
441 at various times in the lifecycle of your package\. The key is the lifecycle
442 event, and the value is the command to run at that point\.
444 See npm help 7 \fBnpm\-scripts\fP to find out more about writing package scripts\.
447 A "config" object can be used to set configuration parameters used in package
448 scripts that persist across upgrades\. For instance, if a package had the
454 , "config" : { "port" : "8080" } }
458 and then had a "start" command that then referenced the
459 \fBnpm_package_config_port\fP environment variable, then the user could
460 override that by doing \fBnpm config set foo:port 8001\fP\|\.
462 See npm help 7 \fBnpm\-config\fP and npm help 7 \fBnpm\-scripts\fP for more on package
466 Dependencies are specified in a simple object that maps a package name to a
467 version range\. The version range is a string which has one or more
468 space\-separated descriptors\. Dependencies can also be identified with a
471 \fBPlease do not put test harnesses or transpilers in your
472 \fBdependencies\fP object\.\fR See \fBdevDependencies\fP, below\.
474 See npm help 7 semver for more details about specifying version ranges\.
477 \fBversion\fP Must match \fBversion\fP exactly
479 \fB>version\fP Must be greater than \fBversion\fP
487 \fB~version\fP "Approximately equivalent to version" See npm help 7 semver
489 \fB^version\fP "Compatible with version" See npm help 7 semver
491 \fB1\.2\.x\fP 1\.2\.0, 1\.2\.1, etc\., but not 1\.3\.0
493 \fBhttp://\.\.\.\fP See 'URLs as Dependencies' below
495 \fB*\fP Matches any version
497 \fB""\fP (just an empty string) Same as \fB*\fP
499 \fBversion1 \- version2\fP Same as \fB>=version1 <=version2\fP\|\.
501 \fBrange1 || range2\fP Passes if either range1 or range2 are satisfied\.
503 \fBgit\.\.\.\fP See 'Git URLs as Dependencies' below
505 \fBuser/repo\fP See 'GitHub URLs' below
507 \fBtag\fP A specific version tagged and published as \fBtag\fP See npm help \fBnpm\-tag\fP
509 \fBpath/path/path\fP See Local Paths below
513 For example, these are all valid:
518 { "foo" : "1\.0\.0 \- 2\.9999\.9999"
519 , "bar" : ">=1\.0\.2 <2\.1\.2"
520 , "baz" : ">1\.0\.2 <=2\.3\.4"
522 , "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
523 , "asd" : "http://asdf\.com/asdf\.tar\.gz"
529 , "dyl" : "file:\.\./dyl"
534 .SS URLs as Dependencies
536 You may specify a tarball URL in place of a version range\.
538 This tarball will be downloaded and installed locally to your package at
540 .SS Git URLs as Dependencies
542 Git urls can be of the form:
546 git://github\.com/user/project\.git#commit\-ish
547 git+ssh://user@hostname:project\.git#commit\-ish
548 git+ssh://user@hostname/project\.git#commit\-ish
549 git+http://user@hostname/project/blah\.git#commit\-ish
550 git+https://user@hostname/project/blah\.git#commit\-ish
554 The \fBcommit\-ish\fP can be any tag, sha, or branch which can be supplied as
555 an argument to \fBgit checkout\fP\|\. The default is \fBmaster\fP\|\.
558 As of version 1\.1\.65, you can refer to GitHub urls as just "foo":
559 "user/foo\-project"\. Just as with git URLs, a \fBcommit\-ish\fP suffix can be
560 included\. For example:
566 "version": "0\.0\.0",
568 "express": "visionmedia/express",
569 "mocha": "visionmedia/mocha#4727d357ea"
576 As of version 2\.0\.0 you can provide a path to a local directory that contains a
577 package\. Local paths can be saved using \fBnpm install \-\-save\fP, using any of
589 in which case they will be normalized to a relative path and added to your
590 \fBpackage\.json\fP\|\. For example:
597 "bar": "file:\.\./foo/bar"
603 This feature is helpful for local offline development and creating
604 tests that require npm installing where you don't want to hit an
605 external server, but should not be used when publishing packages
606 to the public registry\.
609 If someone is planning on downloading and using your module in their
610 program, then they probably don't want or need to download and build
611 the external test or documentation framework that you use\.
613 In this case, it's best to map these additional items in a \fBdevDependencies\fP
616 These things will be installed when doing \fBnpm link\fP or \fBnpm install\fP
617 from the root of a package, and can be managed like any other npm
618 configuration param\. See npm help 7 \fBnpm\-config\fP for more on the topic\.
620 For build steps that are not platform\-specific, such as compiling
621 CoffeeScript or other languages to JavaScript, use the \fBprepublish\fP
622 script to do this, and make the required package a devDependency\.
628 { "name": "ethopia\-waza",
629 "description": "a delightfully fruity coffee varietal",
630 "version": "1\.2\.3",
632 "coffee\-script": "~1\.6\.3"
635 "prepublish": "coffee \-o lib/ \-c src/waza\.coffee"
637 "main": "lib/waza\.js"
642 The \fBprepublish\fP script will be run before publishing, so that users
643 can consume the functionality without requiring them to compile it
644 themselves\. In dev mode (ie, locally running \fBnpm install\fP), it'll
645 run this script as well, so that you can test it easily\.
648 In some cases, you want to express the compatibility of your package with a
649 host tool or library, while not necessarily doing a \fBrequire\fP of this host\.
650 This is usually referred to as a \fIplugin\fR\|\. Notably, your module may be exposing
651 a specific interface, expected and specified by the host documentation\.
658 "name": "tea\-latte",
659 "version": "1\.3\.5",
660 "peerDependencies": {
667 This ensures your package \fBtea\-latte\fP can be installed \fIalong\fR with the second
668 major version of the host package \fBtea\fP only\. \fBnpm install tea\-latte\fP could
669 possibly yield the following dependency graph:
673 ├── tea\-latte@1\.3\.5
678 \fBNOTE: npm versions 1 and 2 will automatically install \fBpeerDependencies\fP if
679 they are not explicitly depended upon higher in the dependency tree\. In the
680 next major version of npm (npm@3), this will no longer be the case\. You will
681 receive a warning that the peerDependency is not installed instead\.\fR The
682 behavior in npms 1 & 2 was frequently confusing and could easily put you into
683 dependency hell, a situation that npm is designed to avoid as much as possible\.
685 Trying to install another plugin with a conflicting requirement will cause an
686 error\. For this reason, make sure your plugin requirement is as broad as
687 possible, and not to lock it down to specific patch versions\.
689 Assuming the host complies with semver \fIhttp://semver\.org/\fR, only changes in
690 the host package's major version will break your plugin\. Thus, if you've worked
691 with every 1\.x version of the host package, use \fB"^1\.0"\fP or \fB"1\.x"\fP to express
692 this\. If you depend on features introduced in 1\.5\.2, use \fB">= 1\.5\.2 < 2"\fP\|\.
693 .SH bundledDependencies
695 Array of package names that will be bundled when publishing the package\.
697 If this is spelled \fB"bundleDependencies"\fP, then that is also honored\.
698 .SH optionalDependencies
700 If a dependency can be used, but you would like npm to proceed if it cannot be
701 found or fails to install, then you may put it in the \fBoptionalDependencies\fP
702 object\. This is a map of package name to version or url, just like the
703 \fBdependencies\fP object\. The difference is that build failures do not cause
704 installation to fail\.
706 It is still your program's responsibility to handle the lack of the
707 dependency\. For example, something like this:
712 var foo = require('foo')
713 var fooVersion = require('foo/package\.json')\.version
717 if ( notGoodFooVersion(fooVersion) ) {
721 // \.\. then later in your program \.\.
729 Entries in \fBoptionalDependencies\fP will override entries of the same name in
730 \fBdependencies\fP, so it's usually best to only put in one place\.
733 You can specify the version of node that your stuff works on:
737 { "engines" : { "node" : ">=0\.10\.3 <0\.12" } }
741 And, like with dependencies, if you don't specify the version (or if you
742 specify "*" as the version), then any version of node will do\.
744 If you specify an "engines" field, then npm will require that "node" be
745 somewhere on that list\. If "engines" is omitted, then npm will just assume
746 that it works on node\.
748 You can also use the "engines" field to specify which versions of npm
749 are capable of properly installing your program\. For example:
753 { "engines" : { "npm" : "~1\.0\.20" } }
757 Note that, unless the user has set the \fBengine\-strict\fP config flag, this
758 field is advisory only\.
761 \fBNOTE: This feature is deprecated and will be removed in npm 3\.0\.0\.\fR
763 If you are sure that your module will \fIdefinitely not\fR run properly on
764 versions of Node/npm other than those specified in the \fBengines\fP object,
765 then you can set \fB"engineStrict": true\fP in your package\.json file\.
766 This will override the user's \fBengine\-strict\fP config setting\.
768 Please do not do this unless you are really very very sure\. If your
769 engines object is something overly restrictive, you can quite easily and
770 inadvertently lock yourself into obscurity and prevent your users from
771 updating to new versions of Node\. Consider this choice carefully\.
774 You can specify which operating systems your
779 "os" : [ "darwin", "linux" ]
783 You can also blacklist instead of whitelist operating systems,
784 just prepend the blacklisted os with a '!':
792 The host operating system is determined by \fBprocess\.platform\fP
794 It is allowed to both blacklist, and whitelist, although there isn't any
795 good reason to do this\.
798 If your code only runs on certain cpu architectures,
799 you can specify which ones\.
803 "cpu" : [ "x64", "ia32" ]
807 Like the \fBos\fP option, you can also blacklist architectures:
811 "cpu" : [ "!arm", "!mips" ]
815 The host architecture is determined by \fBprocess\.arch\fP
818 If your package is primarily a command\-line application that should be
819 installed globally, then set this value to \fBtrue\fP to provide a warning
820 if it is installed locally\.
822 It doesn't actually prevent users from installing it locally, but it
823 does help prevent some confusion if it doesn't work as expected\.
826 If you set \fB"private": true\fP in your package\.json, then npm will refuse
829 This is a way to prevent accidental publication of private repositories\. If
830 you would like to ensure that a given package is only ever published to a
831 specific registry (for example, an internal registry), then use the
832 \fBpublishConfig\fP dictionary described below to override the \fBregistry\fP config
833 param at publish\-time\.
836 This is a set of config values that will be used at publish\-time\. It's
837 especially handy if you want to set the tag, registry or access, so that
838 you can ensure that a given package is not tagged with "latest", published
839 to the global public registry or that a scoped module is private by default\.
841 Any config values can be overridden, but of course only "tag", "registry" and
842 "access" probably matter for the purposes of publishing\.
844 See npm help 7 \fBnpm\-config\fP to see the list of config options that can be
848 npm will default some values based on package contents\.
851 \fB"scripts": {"start": "node server\.js"}\fP
852 If there is a \fBserver\.js\fP file in the root of your package, then npm
853 will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
855 \fB"scripts":{"preinstall": "node\-gyp rebuild"}\fP
856 If there is a \fBbinding\.gyp\fP file in the root of your package, npm will
857 default the \fBpreinstall\fP command to compile using node\-gyp\.
859 \fB"contributors": [\.\.\.]\fP
860 If there is an \fBAUTHORS\fP file in the root of your package, npm will
861 treat each line as a \fBName <email> (url)\fP format, where email and url
862 are optional\. Lines which start with a \fB#\fP or are blank, will be
projects / platform / upstream / nodejs.git / blob