1 .TH "PACKAGE\.JSON" "5" "October 2016" "" ""
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 less than or equal to 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 \fIhttps://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 \fIhttps://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 a string value like this one:
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:
232 \fBCHANGES\fP / \fBCHANGELOG\fP / \fBHISTORY\fP (any casing and file extension)
234 \fBLICENSE\fP / \fBLICENCE\fP
236 The file in the "main" field
240 Conversely, some files are always ignored:
251 \fB\|\.lock\-wscript\fP
253 \fB\|\.wafpickle\-N\fP
261 \fBnpm\-debug\.log\fP
270 The main field is a module ID that is the primary entry point to your program\.
271 That is, if your package is named \fBfoo\fP, and a user installs it, and then does
272 \fBrequire("foo")\fP, then your main module's exports object will be returned\.
274 This should be a module ID relative to the root of your package folder\.
276 For most modules, it makes the most sense to have a main script and often not
280 A lot of packages have one or more executable files that they'd like to
281 install into the PATH\. npm makes this pretty easy (in fact, it uses this
282 feature to install the "npm" executable\.)
284 To use this, supply a \fBbin\fP field in your package\.json which is a map of
285 command name to local file name\. On install, npm will symlink that file into
286 \fBprefix/bin\fP for global installs, or \fB\|\./node_modules/\.bin/\fP for local
289 For example, myapp could have this:
293 { "bin" : { "myapp" : "\./cli\.js" } }
297 So, when you install myapp, it'll create a symlink from the \fBcli\.js\fP script to
298 \fB/usr/local/bin/myapp\fP\|\.
300 If you have a single executable, and its name should be the name
301 of the package, then you can just supply it as a string\. For example:
305 { "name": "my\-program"
306 , "version": "1\.2\.5"
307 , "bin": "\./path/to/program" }
311 would be the same as this:
315 { "name": "my\-program"
316 , "version": "1\.2\.5"
317 , "bin" : { "my\-program" : "\./path/to/program" } }
321 Please make sure that your file(s) referenced in \fBbin\fP starts with
322 \fB#!/usr/bin/env node\fP, otherwise the scripts are started without the node
326 Specify either a single file or an array of filenames to put in place for the
327 \fBman\fP program to find\.
329 If only a single file is provided, then it's installed such that it is the
330 result from \fBman <pkgname>\fP, regardless of its actual filename\. For example:
335 , "version" : "1\.2\.3"
336 , "description" : "A packaged foo fooer for fooing foos"
338 , "man" : "\./man/doc\.1"
343 would link the \fB\|\./man/doc\.1\fP file in such that it is the target for \fBman foo\fP
345 If the filename doesn't start with the package name, then it's prefixed\.
351 , "version" : "1\.2\.3"
352 , "description" : "A packaged foo fooer for fooing foos"
354 , "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
359 will create files to do \fBman foo\fP and \fBman foo\-bar\fP\|\.
361 Man files must end with a number, and optionally a \fB\|\.gz\fP suffix if they are
362 compressed\. The number dictates which man section the file is installed into\.
367 , "version" : "1\.2\.3"
368 , "description" : "A packaged foo fooer for fooing foos"
370 , "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
375 will create entries for \fBman foo\fP and \fBman 2 foo\fP
378 The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
379 few ways that you can indicate the structure of your package using a \fBdirectories\fP
380 object\. If you look at npm's package\.json \fIhttps://registry\.npmjs\.org/npm/latest\fR,
381 you'll see that it has directories for doc, lib, and man\.
383 In the future, this information may be used in other creative ways\.
386 Tell people where the bulk of your library is\. Nothing special is done
387 with the lib folder in any way, but it's useful meta info\.
390 If you specify a \fBbin\fP directory in \fBdirectories\.bin\fP, all the files in
391 that folder will be added\.
393 Because of the way the \fBbin\fP directive works, specifying both a
394 \fBbin\fP path and setting \fBdirectories\.bin\fP is an error\. If you want to
395 specify individual files, use \fBbin\fP, and for all the files in an
396 existing \fBbin\fP directory, use \fBdirectories\.bin\fP\|\.
399 A folder that is full of man pages\. Sugar to generate a "man" array by
403 Put markdown files in here\. Eventually, these will be displayed nicely,
405 .SS directories\.example
407 Put example scripts in here\. Someday, it might be exposed in some clever way\.
408 .SS directories\.test
410 Put your tests in here\. It is currently not exposed, but it might be in the
414 Specify the place where your code lives\. This is helpful for people who
415 want to contribute\. If the git repo is on GitHub, then the \fBnpm docs\fP
416 command will be able to find you\.
424 , "url" : "https://github\.com/npm/npm\.git"
429 , "url" : "https://v8\.googlecode\.com/svn/trunk/"
434 The URL should be a publicly available (perhaps read\-only) url that can be handed
435 directly to a VCS program without any modification\. It should not be a url to an
436 html project page that you put in your browser\. It's for computers\.
438 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
439 shortcut syntax you use for \fBnpm install\fP:
443 "repository": "npm/npm"
445 "repository": "gist:11081aaa281"
447 "repository": "bitbucket:example/repo"
449 "repository": "gitlab:another/repo"
454 The "scripts" property is a dictionary containing script commands that are run
455 at various times in the lifecycle of your package\. The key is the lifecycle
456 event, and the value is the command to run at that point\.
458 See npm help 7 \fBnpm\-scripts\fP to find out more about writing package scripts\.
461 A "config" object can be used to set configuration parameters used in package
462 scripts that persist across upgrades\. For instance, if a package had the
468 , "config" : { "port" : "8080" } }
472 and then had a "start" command that then referenced the
473 \fBnpm_package_config_port\fP environment variable, then the user could
474 override that by doing \fBnpm config set foo:port 8001\fP\|\.
476 See npm help 7 \fBnpm\-config\fP and npm help 7 \fBnpm\-scripts\fP for more on package
480 Dependencies are specified in a simple object that maps a package name to a
481 version range\. The version range is a string which has one or more
482 space\-separated descriptors\. Dependencies can also be identified with a
485 \fBPlease do not put test harnesses or transpilers in your
486 \fBdependencies\fP object\.\fR See \fBdevDependencies\fP, below\.
488 See npm help 7 semver for more details about specifying version ranges\.
491 \fBversion\fP Must match \fBversion\fP exactly
493 \fB>version\fP Must be greater than \fBversion\fP
501 \fB~version\fP "Approximately equivalent to version" See npm help 7 semver
503 \fB^version\fP "Compatible with version" See npm help 7 semver
505 \fB1\.2\.x\fP 1\.2\.0, 1\.2\.1, etc\., but not 1\.3\.0
507 \fBhttp://\.\.\.\fP See 'URLs as Dependencies' below
509 \fB*\fP Matches any version
511 \fB""\fP (just an empty string) Same as \fB*\fP
513 \fBversion1 \- version2\fP Same as \fB>=version1 <=version2\fP\|\.
515 \fBrange1 || range2\fP Passes if either range1 or range2 are satisfied\.
517 \fBgit\.\.\.\fP See 'Git URLs as Dependencies' below
519 \fBuser/repo\fP See 'GitHub URLs' below
521 \fBtag\fP A specific version tagged and published as \fBtag\fP See npm help \fBnpm\-tag\fP
523 \fBpath/path/path\fP See Local Paths \fI#local\-paths\fR below
527 For example, these are all valid:
532 { "foo" : "1\.0\.0 \- 2\.9999\.9999"
533 , "bar" : ">=1\.0\.2 <2\.1\.2"
534 , "baz" : ">1\.0\.2 <=2\.3\.4"
536 , "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
537 , "asd" : "http://asdf\.com/asdf\.tar\.gz"
543 , "dyl" : "file:\.\./dyl"
548 .SS URLs as Dependencies
550 You may specify a tarball URL in place of a version range\.
552 This tarball will be downloaded and installed locally to your package at
554 .SS Git URLs as Dependencies
556 Git urls can be of the form:
560 git://github\.com/user/project\.git#commit\-ish
561 git+ssh://user@hostname:project\.git#commit\-ish
562 git+ssh://user@hostname/project\.git#commit\-ish
563 git+http://user@hostname/project/blah\.git#commit\-ish
564 git+https://user@hostname/project/blah\.git#commit\-ish
568 The \fBcommit\-ish\fP can be any tag, sha, or branch which can be supplied as
569 an argument to \fBgit checkout\fP\|\. The default is \fBmaster\fP\|\.
572 As of version 1\.1\.65, you can refer to GitHub urls as just "foo":
573 "user/foo\-project"\. Just as with git URLs, a \fBcommit\-ish\fP suffix can be
574 included\. For example:
580 "version": "0\.0\.0",
582 "express": "visionmedia/express",
583 "mocha": "visionmedia/mocha#4727d357ea"
590 As of version 2\.0\.0 you can provide a path to a local directory that contains a
591 package\. Local paths can be saved using \fBnpm install \-\-save\fP, using any of
603 in which case they will be normalized to a relative path and added to your
604 \fBpackage\.json\fP\|\. For example:
611 "bar": "file:\.\./foo/bar"
617 This feature is helpful for local offline development and creating
618 tests that require npm installing where you don't want to hit an
619 external server, but should not be used when publishing packages
620 to the public registry\.
623 If someone is planning on downloading and using your module in their
624 program, then they probably don't want or need to download and build
625 the external test or documentation framework that you use\.
627 In this case, it's best to map these additional items in a \fBdevDependencies\fP
630 These things will be installed when doing \fBnpm link\fP or \fBnpm install\fP
631 from the root of a package, and can be managed like any other npm
632 configuration param\. See npm help 7 \fBnpm\-config\fP for more on the topic\.
634 For build steps that are not platform\-specific, such as compiling
635 CoffeeScript or other languages to JavaScript, use the \fBprepublish\fP
636 script to do this, and make the required package a devDependency\.
642 { "name": "ethopia\-waza",
643 "description": "a delightfully fruity coffee varietal",
644 "version": "1\.2\.3",
646 "coffee\-script": "~1\.6\.3"
649 "prepublish": "coffee \-o lib/ \-c src/waza\.coffee"
651 "main": "lib/waza\.js"
656 The \fBprepublish\fP script will be run before publishing, so that users
657 can consume the functionality without requiring them to compile it
658 themselves\. In dev mode (ie, locally running \fBnpm install\fP), it'll
659 run this script as well, so that you can test it easily\.
662 In some cases, you want to express the compatibility of your package with a
663 host tool or library, while not necessarily doing a \fBrequire\fP of this host\.
664 This is usually referred to as a \fIplugin\fR\|\. Notably, your module may be exposing
665 a specific interface, expected and specified by the host documentation\.
672 "name": "tea\-latte",
673 "version": "1\.3\.5",
674 "peerDependencies": {
681 This ensures your package \fBtea\-latte\fP can be installed \fIalong\fR with the second
682 major version of the host package \fBtea\fP only\. \fBnpm install tea\-latte\fP could
683 possibly yield the following dependency graph:
687 ├── tea\-latte@1\.3\.5
688 └── tea@2\.2\.0
692 \fBNOTE: npm versions 1 and 2 will automatically install \fBpeerDependencies\fP if
693 they are not explicitly depended upon higher in the dependency tree\. In the
694 next major version of npm (npm@3), this will no longer be the case\. You will
695 receive a warning that the peerDependency is not installed instead\.\fR The
696 behavior in npms 1 & 2 was frequently confusing and could easily put you into
697 dependency hell, a situation that npm is designed to avoid as much as possible\.
699 Trying to install another plugin with a conflicting requirement will cause an
700 error\. For this reason, make sure your plugin requirement is as broad as
701 possible, and not to lock it down to specific patch versions\.
703 Assuming the host complies with semver \fIhttp://semver\.org/\fR, only changes in
704 the host package's major version will break your plugin\. Thus, if you've worked
705 with every 1\.x version of the host package, use \fB"^1\.0"\fP or \fB"1\.x"\fP to express
706 this\. If you depend on features introduced in 1\.5\.2, use \fB">= 1\.5\.2 < 2"\fP\|\.
707 .SH bundledDependencies
709 This defines an array of package names that will be bundled when publishing the package\.
711 In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the \fBbundledDependencies\fP array and executing \fBnpm pack\fP\|\.
714 If we define a package\.json like this:
719 "name": "awesome\-web\-framework",
720 "version": "1\.0\.0",
721 "bundledDependencies": [
722 'renderized', 'super\-streams'
728 we can obtain \fBawesome\-web\-framework\-1\.0\.0\.tgz\fP file by running \fBnpm pack\fP\|\. This file contains the dependencies \fBrenderized\fP and \fBsuper\-streams\fP which can be installed in a new project by executing \fBnpm install awesome\-web\-framework\-1\.0\.0\.tgz\fP\|\.
730 If this is spelled \fB"bundleDependencies"\fP, then that is also honored\.
731 .SH optionalDependencies
733 If a dependency can be used, but you would like npm to proceed if it cannot be
734 found or fails to install, then you may put it in the \fBoptionalDependencies\fP
735 object\. This is a map of package name to version or url, just like the
736 \fBdependencies\fP object\. The difference is that build failures do not cause
737 installation to fail\.
739 It is still your program's responsibility to handle the lack of the
740 dependency\. For example, something like this:
745 var foo = require('foo')
746 var fooVersion = require('foo/package\.json')\.version
750 if ( notGoodFooVersion(fooVersion) ) {
754 // \.\. then later in your program \.\.
762 Entries in \fBoptionalDependencies\fP will override entries of the same name in
763 \fBdependencies\fP, so it's usually best to only put in one place\.
766 You can specify the version of node that your stuff works on:
770 { "engines" : { "node" : ">=0\.10\.3 <0\.12" } }
774 And, like with dependencies, if you don't specify the version (or if you
775 specify "*" as the version), then any version of node will do\.
777 If you specify an "engines" field, then npm will require that "node" be
778 somewhere on that list\. If "engines" is omitted, then npm will just assume
779 that it works on node\.
781 You can also use the "engines" field to specify which versions of npm
782 are capable of properly installing your program\. For example:
786 { "engines" : { "npm" : "~1\.0\.20" } }
790 Unless the user has set the \fBengine\-strict\fP config flag, this
791 field is advisory only will produce warnings when your package is installed as a dependency\.
794 \fBNOTE: This feature is deprecated and will be removed in npm 3\.0\.0\.\fR
796 If you are sure that your module will \fIdefinitely not\fR run properly on
797 versions of Node/npm other than those specified in the \fBengines\fP object,
798 then you can set \fB"engineStrict": true\fP in your package\.json file\.
799 This will override the user's \fBengine\-strict\fP config setting\.
801 Please do not do this unless you are really very very sure\. If your
802 engines object is something overly restrictive, you can quite easily and
803 inadvertently lock yourself into obscurity and prevent your users from
804 updating to new versions of Node\. Consider this choice carefully\.
807 You can specify which operating systems your
812 "os" : [ "darwin", "linux" ]
816 You can also blacklist instead of whitelist operating systems,
817 just prepend the blacklisted os with a '!':
825 The host operating system is determined by \fBprocess\.platform\fP
827 It is allowed to both blacklist, and whitelist, although there isn't any
828 good reason to do this\.
831 If your code only runs on certain cpu architectures,
832 you can specify which ones\.
836 "cpu" : [ "x64", "ia32" ]
840 Like the \fBos\fP option, you can also blacklist architectures:
844 "cpu" : [ "!arm", "!mips" ]
848 The host architecture is determined by \fBprocess\.arch\fP
851 If your package is primarily a command\-line application that should be
852 installed globally, then set this value to \fBtrue\fP to provide a warning
853 if it is installed locally\.
855 It doesn't actually prevent users from installing it locally, but it
856 does help prevent some confusion if it doesn't work as expected\.
859 If you set \fB"private": true\fP in your package\.json, then npm will refuse
862 This is a way to prevent accidental publication of private repositories\. If
863 you would like to ensure that a given package is only ever published to a
864 specific registry (for example, an internal registry), then use the
865 \fBpublishConfig\fP dictionary described below to override the \fBregistry\fP config
866 param at publish\-time\.
869 This is a set of config values that will be used at publish\-time\. It's
870 especially handy if you want to set the tag, registry or access, so that
871 you can ensure that a given package is not tagged with "latest", published
872 to the global public registry or that a scoped module is private by default\.
874 Any config values can be overridden, but of course only "tag", "registry" and
875 "access" probably matter for the purposes of publishing\.
877 See npm help 7 \fBnpm\-config\fP to see the list of config options that can be
881 npm will default some values based on package contents\.
884 \fB"scripts": {"start": "node server\.js"}\fP
885 If there is a \fBserver\.js\fP file in the root of your package, then npm
886 will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
888 \fB"scripts":{"install": "node\-gyp rebuild"}\fP
889 If there is a \fBbinding\.gyp\fP file in the root of your package and you have not defined an \fBinstall\fP or \fBpreinstall\fP script, npm will
890 default the \fBinstall\fP command to compile using node\-gyp\.
892 \fB"contributors": [\.\.\.]\fP
893 If there is an \fBAUTHORS\fP file in the root of your package, npm will
894 treat each line as a \fBName <email> (url)\fP format, where email and url
895 are optional\. Lines which start with a \fB#\fP or are blank, will be
Code Review / simantics / district.git / blob