1PACKAGE.JSON(5) PACKAGE.JSON(5)
2
6 package.json - Specifics of npm's package.json handling
7
9 This document is all you need to know about what's required in your
10 package.json file. It must be actual JSON, not just a JavaScript
11 object literal.
12 A lot of the behavior described in this document is affected by the
14 config settings described in npm help 7 npm-config.
15
17 If you plan to publish your package, the most important things in your
18 package.json are the name and version fields as they will be required.
19 The name and version together form an identifier that is assumed to be
20 completely unique. Changes to the package should come along with
21 changes to the version. If you don't plan to publish your package, the
22 name and version fields are optional.
23 The name is what your thing is called.
25 Some rules:
27 · The name must be less than or equal to 214 characters. This includes
29 the scope for scoped packages.
30 · The name can't start with a dot or an underscore.
32 · New packages must not have uppercase letters in the name.
34 · The name ends up being part of a URL, an argument on the command
36 line, and a folder name. Therefore, the name can't contain any
37 non-URL-safe characters.
38 Some tips:
41 · Don't use the same name as a core Node module.
43 · Don't put "js" or "node" in the name. It's assumed that it's js,
45 since you're writing a package.json file, and you can specify the
46 engine using the "engines" field. (See below.)
47 · The name will probably be passed as an argument to require(), so it
49 should be something short, but also reasonably descriptive.
50 · You may want to check the npm registry to see if there's something by
52 that name already, before you get too attached to it.
53 https://www.npmjs.com/
54 A name can be optionally prefixed by a scope, e.g. @myorg/mypackage.
57 See npm help 7 npm-scope for more detail.
58
60 If you plan to publish your package, the most important things in your
61 package.json are the name and version fields as they will be required.
62 The name and version together form an identifier that is assumed to be
63 completely unique. Changes to the package should come along with
64 changes to the version. If you don't plan to publish your package, the
65 name and version fields are optional.
66 Version must be parseable by node-semver
68 https://github.com/isaacs/node-semver, which is bundled with npm as a
69 dependency. (npm install semver to use it yourself.)
70 More on version numbers and ranges at npm help 7 semver.
72
74 Put a description in it. It's a string. This helps people discover
75 your package, as it's listed in npm search.
76
78 Put keywords in it. It's an array of strings. This helps people dis‐
79 cover your package as it's listed in npm search.
80
82 The url to the project homepage.
83 Example:
85 "homepage": "https://github.com/owner/project#readme"
87
89 The url to your project's issue tracker and / or the email address to
90 which issues should be reported. These are helpful for people who
91 encounter issues with your package.
92 It should look like this:
94 { "url" : "https://github.com/owner/project/issues"
96 , "email" : "project@hostname.com"
97 }
98 You can specify either one or both values. If you want to provide only
100 a url, you can specify the value for "bugs" as a simple string instead
101 of an object.
102 If a url is provided, it will be used by the npm bugs command.
104
106 You should specify a license for your package so that people know how
107 they are permitted to use it, and any restrictions you're placing on
108 it.
109 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
112 this:
113 { "license" : "BSD-3-Clause" }
115 You can check the full list of SPDX license IDs
117 https://spdx.org/licenses/. Ideally you should pick one that is OSI
118 https://opensource.org/licenses/alphabetical approved.
119 If your package is licensed under multiple common licenses, use an SPDX
121 license expression syntax version 2.0 string
122 https://www.npmjs.com/package/spdx, like this:
123 { "license" : "(ISC OR GPL-3.0)" }
125 If you are using a license that hasn't been assigned an SPDX identi‐
127 fier, or if you are using a custom license, use a string value like
128 this one:
129 { "license" : "SEE LICENSE IN <filename>" }
131 Then include a file named <filename> at the top level of the package.
133 Some old packages used license objects or a "licenses" property con‐
135 taining an array of license objects:
136 // Not valid metadata
138 { "license" :
139 { "type" : "ISC"
140 , "url" : "https://opensource.org/licenses/ISC"
141 }
142 }
143 // Not valid metadata
145 { "licenses" :
146 [
147 { "type": "MIT"
148 , "url": "https://www.opensource.org/licenses/mit-license.php"
149 }
150 , { "type": "Apache-2.0"
151 , "url": "https://opensource.org/licenses/apache2.0.php"
152 }
153 ]
154 }
155 Those styles are now deprecated. Instead, use SPDX expressions, like
157 this:
158 { "license": "ISC" }
160 { "license": "(MIT OR Apache-2.0)" }
162 Finally, if you do not wish to grant others the right to use a private
164 or unpublished package under any terms:
165 { "license": "UNLICENSED" }
167 Consider also setting "private": true to prevent accidental publica‐
169 tion.
170
172 The "author" is one person. "contributors" is an array of people. A
173 "person" is an object with a "name" field and optionally "url" and
174 "email", like this:
175 { "name" : "Barney Rubble"
177 , "email" : "b@rubble.com"
178 , "url" : "http://barnyrubble.tumblr.com/"
179 }
180 Or you can shorten that all into a single string, and npm will parse it
182 for you:
183 "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
185 Both email and url are optional either way.
187 npm also sets a top-level "maintainers" field with your npm user info.
189
191 The optional files field is an array of file patterns that describes
192 the entries to be included when your package is installed as a depen‐
193 dency. File patterns follow a similar syntax to .gitignore, but
194 reversed: including a file, directory, or glob pattern (*, **/*, and
195 such) will make it so that file is included in the tarball when it's
196 packed. Omitting the field will make it default to ["*"], which means
197 it will include all files.
198 Some special files and directories are also included or excluded
200 regardless of whether they exist in the files array (see below).
201 You can also provide a .npmignore file in the root of your package or
203 in subdirectories, which will keep files from being included. At the
204 root of your package it will not override the "files" field, but in
205 subdirectories it will. The .npmignore file works just like a .gitig‐
206 nore. If there is a .gitignore file, and .npmignore is missing, .gitig‐
207 nore's contents will be used instead.
208 Files included with the "package.json#files" field cannot be excluded
210 through .npmignore or .gitignore.
211 Certain files are always included, regardless of settings:
213 · package.json
215 · README
217 · CHANGES / CHANGELOG / HISTORY
219 · LICENSE / LICENCE
221 · NOTICE
223 · The file in the "main" field
225 README, CHANGES, LICENSE & NOTICE can have any case and extension.
228 Conversely, some files are always ignored:
230 · .git
232 · CVS
234 · .svn
236 · .hg
238 · .lock-wscript
240 · .wafpickle-N
242 · .*.swp
244 · .DS_Store
246 · ._*
248 · npm-debug.log
250 · .npmrc
252 · node_modules
254 · config.gypi
256 · *.orig
258 · package-lock.json (use shrinkwrap instead)
260
263 The main field is a module ID that is the primary entry point to your
264 program. That is, if your package is named foo, and a user installs
265 it, and then does require("foo"), then your main module's exports
266 object will be returned.
267 This should be a module ID relative to the root of your package folder.
269 For most modules, it makes the most sense to have a main script and
271 often not much else.
272
274 If your module is meant to be used client-side the browser field should
275 be used instead of the main field. This is helpful to hint users that
276 it might rely on primitives that aren't available in Node.js modules.
277 (e.g. window)
278
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
282 this feature to install the "npm" executable.)
283 To use this, supply a bin field in your package.json which is a map of
285 command name to local file name. On install, npm will symlink that file
286 into prefix/bin for global installs, or ./node_modules/.bin/ for local
287 installs.
288 For example, myapp could have this:
290 { "bin" : { "myapp" : "./cli.js" } }
292 So, when you install myapp, it'll create a symlink from the cli.js
294 script to /usr/local/bin/myapp.
295 If you have a single executable, and its name should be the name of the
297 package, then you can just supply it as a string. For example:
298 { "name": "my-program"
300 , "version": "1.2.5"
301 , "bin": "./path/to/program" }
302 would be the same as this:
304 { "name": "my-program"
306 , "version": "1.2.5"
307 , "bin" : { "my-program" : "./path/to/program" } }
308 Please make sure that your file(s) referenced in bin starts with
310 #!/usr/bin/env node, otherwise the scripts are started without the node
311 executable!
312
314 Specify either a single file or an array of filenames to put in place
315 for the man program to find.
316 If only a single file is provided, then it's installed such that it is
318 the result from man <pkgname>, regardless of its actual filename. For
319 example:
320 { "name" : "foo"
322 , "version" : "1.2.3"
323 , "description" : "A packaged foo fooer for fooing foos"
324 , "main" : "foo.js"
325 , "man" : "./man/doc.1"
326 }
327 would link the ./man/doc.1 file in such that it is the target for man
329 foo
330 If the filename doesn't start with the package name, then it's pre‐
332 fixed. So, this:
333 { "name" : "foo"
335 , "version" : "1.2.3"
336 , "description" : "A packaged foo fooer for fooing foos"
337 , "main" : "foo.js"
338 , "man" : [ "./man/foo.1", "./man/bar.1" ]
339 }
340 will create files to do man foo and man foo-bar.
342 Man files must end with a number, and optionally a .gz suffix if they
344 are compressed. The number dictates which man section the file is
345 installed into.
346 { "name" : "foo"
348 , "version" : "1.2.3"
349 , "description" : "A packaged foo fooer for fooing foos"
350 , "main" : "foo.js"
351 , "man" : [ "./man/foo.1", "./man/foo.2" ]
352 }
353 will create entries for man foo and man 2 foo
355
357 The CommonJS Packages http://wiki.commonjs.org/wiki/Packages/1.0 spec
358 details a few ways that you can indicate the structure of your package
359 using a directories object. If you look at npm's package.json
360 https://registry.npmjs.org/npm/latest, you'll see that it has directo‐
361 ries for doc, lib, and man.
362 In the future, this information may be used in other creative ways.
364 directories.lib
366 Tell people where the bulk of your library is. Nothing special is done
367 with the lib folder in any way, but it's useful meta info.
368 directories.bin
370 If you specify a bin directory in directories.bin, all the files in
371 that folder will be added.
372 Because of the way the bin directive works, specifying both a bin path
374 and setting directories.bin is an error. If you want to specify indi‐
375 vidual files, use bin, and for all the files in an existing bin direc‐
376 tory, use directories.bin.
377 directories.man
379 A folder that is full of man pages. Sugar to generate a "man" array by
380 walking the folder.
381 directories.doc
383 Put markdown files in here. Eventually, these will be displayed
384 nicely, maybe, someday.
385 directories.example
387 Put example scripts in here. Someday, it might be exposed in some
388 clever way.
389 directories.test
391 Put your tests in here. It is currently not exposed, but it might be in
392 the future.
393
395 Specify the place where your code lives. This is helpful for people who
396 want to contribute. If the git repo is on GitHub, then the npm docs
397 command will be able to find you.
398 Do it like this:
400 "repository": {
402 "type" : "git",
403 "url" : "https://github.com/npm/cli.git"
404 }
405 "repository": {
407 "type" : "svn",
408 "url" : "https://v8.googlecode.com/svn/trunk/"
409 }
410 The URL should be a publicly available (perhaps read-only) url that can
412 be handed directly to a VCS program without any modification. It
413 should not be a url to an html project page that you put in your
414 browser. It's for computers.
415 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use
417 the same shortcut syntax you use for npm install:
418 "repository": "npm/npm"
420 "repository": "github:user/repo"
422 "repository": "gist:11081aaa281"
424 "repository": "bitbucket:user/repo"
426 "repository": "gitlab:user/repo"
428 If the package.json for your package is not in the root directory (for
430 example if it is part of a monorepo), you can specify the directory in
431 which it lives:
432 "repository": {
434 "type" : "git",
435 "url" : "https://github.com/facebook/react.git",
436 "directory": "packages/react-dom"
437 }
438
440 The "scripts" property is a dictionary containing script commands that
441 are run at various times in the lifecycle of your package. The key is
442 the lifecycle event, and the value is the command to run at that point.
443 See npm help 7 npm-scripts to find out more about writing package
445 scripts.
446
448 A "config" object can be used to set configuration parameters used in
449 package scripts that persist across upgrades. For instance, if a pack‐
450 age had the following:
451 { "name" : "foo"
453 , "config" : { "port" : "8080" } }
454 and then had a "start" command that then referenced the npm_pack‐
456 age_config_port environment variable, then the user could override that
457 by doing npm config set foo:port 8001.
458 See npm help 7 npm-config and npm help 7 npm-scripts for more on pack‐
460 age configs.
461
463 Dependencies are specified in a simple object that maps a package name
464 to a version range. The version range is a string which has one or more
465 space-separated descriptors. Dependencies can also be identified with
466 a tarball or git URL.
467 Please do not put test harnesses or transpilers in your dependencies
469 object. See devDependencies, below.
470 See npm help 7 semver for more details about specifying version ranges.
472 · version Must match version exactly
474 · >version Must be greater than version
476 · >=version etc
478 · <version
480 · <=version
482 · ~version "Approximately equivalent to version" See npm help 7 semver
484 · ^version "Compatible with version" See npm help 7 semver
486 · 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
488 · http://... See 'URLs as Dependencies' below
490 · * Matches any version
492 · "" (just an empty string) Same as *
494 · version1 - version2 Same as >=version1 <=version2.
496 · range1 || range2 Passes if either range1 or range2 are satisfied.
498 · git... See 'Git URLs as Dependencies' below
500 · user/repo See 'GitHub URLs' below
502 · tag A specific version tagged and published as tag See npm help
504 npm-dist-tag
505 · path/path/path See Local Paths #local-paths below
507 For example, these are all valid:
510 { "dependencies" :
512 { "foo" : "1.0.0 - 2.9999.9999"
513 , "bar" : ">=1.0.2 <2.1.2"
514 , "baz" : ">1.0.2 <=2.3.4"
515 , "boo" : "2.0.1"
516 , "qux" : "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0"
517 , "asd" : "http://asdf.com/asdf.tar.gz"
518 , "til" : "~1.2"
519 , "elf" : "~1.2.3"
520 , "two" : "2.x"
521 , "thr" : "3.3.x"
522 , "lat" : "latest"
523 , "dyl" : "file:../dyl"
524 }
525 }
526 URLs as Dependencies
528 You may specify a tarball URL in place of a version range.
529 This tarball will be downloaded and installed locally to your package
531 at install time.
532 Git URLs as Dependencies
534 Git urls are of the form:
535 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
537 <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
539 If #<commit-ish> is provided, it will be used to clone exactly that
541 commit. If the commit-ish has the format #semver:<semver>, <semver> can
542 be any valid semver range or exact version, and npm will look for any
543 tags or refs matching that range in the remote repository, much as it
544 would for a registry dependency. If neither #<commit-ish> or
545 #semver:<semver> is specified, then master is used.
546 Examples:
548 git+ssh://git@github.com:npm/cli.git#v1.0.27
550 git+ssh://git@github.com:npm/cli#semver:^5.0
551 git+https://isaacs@github.com/npm/cli.git
552 git://github.com/npm/cli.git#v1.0.27
553 GitHub URLs
555 As of version 1.1.65, you can refer to GitHub urls as just "foo":
556 "user/foo-project". Just as with git URLs, a commit-ish suffix can be
557 included. For example:
558 {
560 "name": "foo",
561 "version": "0.0.0",
562 "dependencies": {
563 "express": "expressjs/express",
564 "mocha": "mochajs/mocha#4727d357ea",
565 "module": "user/repo#feature\/branch"
566 }
567 }
568 Local Paths
570 As of version 2.0.0 you can provide a path to a local directory that
571 contains a package. Local paths can be saved using npm install -S or
572 npm install --save, using any of these forms:
573 ../foo/bar
575 ~/foo/bar
576 ./foo/bar
577 /foo/bar
578 in which case they will be normalized to a relative path and added to
580 your package.json. For example:
581 {
583 "name": "baz",
584 "dependencies": {
585 "bar": "file:../foo/bar"
586 }
587 }
588 This feature is helpful for local offline development and creating
590 tests that require npm installing where you don't want to hit an exter‐
591 nal server, but should not be used when publishing packages to the pub‐
592 lic registry.
593
595 If someone is planning on downloading and using your module in their
596 program, then they probably don't want or need to download and build
597 the external test or documentation framework that you use.
598 In this case, it's best to map these additional items in a devDependen‐
600 cies object.
601 These things will be installed when doing npm link or npm install from
603 the root of a package, and can be managed like any other npm configura‐
604 tion param. See npm help 7 npm-config for more on the topic.
605 For build steps that are not platform-specific, such as compiling Cof‐
607 feeScript or other languages to JavaScript, use the prepare script to
608 do this, and make the required package a devDependency.
609 For example:
611 { "name": "ethopia-waza",
613 "description": "a delightfully fruity coffee varietal",
614 "version": "1.2.3",
615 "devDependencies": {
616 "coffee-script": "~1.6.3"
617 },
618 "scripts": {
619 "prepare": "coffee -o lib/ -c src/waza.coffee"
620 },
621 "main": "lib/waza.js"
622 }
623 The prepare script will be run before publishing, so that users can
625 consume the functionality without requiring them to compile it them‐
626 selves. In dev mode (ie, locally running npm install), it'll run this
627 script as well, so that you can test it easily.
628
630 In some cases, you want to express the compatibility of your package
631 with a host tool or library, while not necessarily doing a require of
632 this host. This is usually referred to as a plugin. Notably, your mod‐
633 ule may be exposing a specific interface, expected and specified by the
634 host documentation.
635 For example:
637 {
639 "name": "tea-latte",
640 "version": "1.3.5",
641 "peerDependencies": {
642 "tea": "2.x"
643 }
644 }
645 This ensures your package tea-latte can be installed along with the
647 second major version of the host package tea only. npm install
648 tea-latte could possibly yield the following dependency graph:
649 ├── tea-latte@1.3.5
651 └── tea@2.2.0
652 NOTE: npm versions 1 and 2 will automatically install peerDependencies
654 if they are not explicitly depended upon higher in the dependency tree.
655 In the next major version of npm (npm@3), this will no longer be the
656 case. You will receive a warning that the peerDependency is not
657 installed instead. The behavior in npms 1 & 2 was frequently confusing
658 and could easily put you into dependency hell, a situation that npm is
659 designed to avoid as much as possible.
660 Trying to install another plugin with a conflicting requirement will
662 cause an error. For this reason, make sure your plugin requirement is
663 as broad as possible, and not to lock it down to specific patch ver‐
664 sions.
665 Assuming the host complies with semver https://semver.org/, only
667 changes in the host package's major version will break your plugin.
668 Thus, if you've worked with every 1.x version of the host package, use
669 "^1.0" or "1.x" to express this. If you depend on features introduced
670 in 1.5.2, use ">= 1.5.2 < 2".
671
673 This defines an array of package names that will be bundled when pub‐
674 lishing the package.
675 In cases where you need to preserve npm packages locally or have them
677 available through a single file download, you can bundle the packages
678 in a tarball file by specifying the package names in the bundledDepen‐
679 dencies array and executing npm pack.
680 For example:
682 If we define a package.json like this:
684 {
686 "name": "awesome-web-framework",
687 "version": "1.0.0",
688 "bundledDependencies": [
689 "renderized", "super-streams"
690 ]
691 }
692 we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack.
694 This file contains the dependencies renderized and super-streams which
695 can be installed in a new project by executing npm install awe‐
696 some-web-framework-1.0.0.tgz. Note that the package names do not
697 include any versions, as that information is specified in dependencies.
698 If this is spelled "bundleDependencies", then that is also honored.
700
702 If a dependency can be used, but you would like npm to proceed if it
703 cannot be found or fails to install, then you may put it in the option‐
704 alDependencies object. This is a map of package name to version or
705 url, just like the dependencies object. The difference is that build
706 failures do not cause installation to fail.
707 It is still your program's responsibility to handle the lack of the
709 dependency. For example, something like this:
710 try {
712 var foo = require('foo')
713 var fooVersion = require('foo/package.json').version
714 } catch (er) {
715 foo = null
716 }
717 if ( notGoodFooVersion(fooVersion) ) {
718 foo = null
719 }
720 // .. then later in your program ..
722 if (foo) {
724 foo.doFooThings()
725 }
726 Entries in optionalDependencies will override entries of the same name
728 in dependencies, so it's usually best to only put in one place.
729
731 You can specify the version of node that your stuff works on:
732 { "engines" : { "node" : ">=0.10.3 <0.12" } }
734 And, like with dependencies, if you don't specify the version (or if
736 you specify "*" as the version), then any version of node will do.
737 If you specify an "engines" field, then npm will require that "node" be
739 somewhere on that list. If "engines" is omitted, then npm will just
740 assume that it works on node.
741 You can also use the "engines" field to specify which versions of npm
743 are capable of properly installing your program. For example:
744 { "engines" : { "npm" : "~1.0.20" } }
746 Unless the user has set the engine-strict config flag, this field is
748 advisory only and will only produce warnings when your package is
749 installed as a dependency.
750
752 This feature was removed in npm 3.0.0
753 Prior to npm 3.0.0, this feature was used to treat this package as if
755 the user had set engine-strict. It is no longer used.
756
758 You can specify which operating systems your module will run on:
759 "os" : [ "darwin", "linux" ]
761 You can also blacklist instead of whitelist operating systems, just
763 prepend the blacklisted os with a '!':
764 "os" : [ "!win32" ]
766 The host operating system is determined by process.platform
768 It is allowed to both blacklist, and whitelist, although there isn't
770 any good reason to do this.
771
773 If your code only runs on certain cpu architectures, you can specify
774 which ones.
775 "cpu" : [ "x64", "ia32" ]
777 Like the os option, you can also blacklist architectures:
779 "cpu" : [ "!arm", "!mips" ]
781 The host architecture is determined by process.arch
783
785 DEPRECATED
786 This option used to trigger an npm warning, but it will no longer warn.
788 It is purely there for informational purposes. It is now recommended
789 that you install any binaries as local devDependencies wherever possi‐
790 ble.
791
793 If you set "private": true in your package.json, then npm will refuse
794 to publish it.
795 This is a way to prevent accidental publication of private reposito‐
797 ries. If you would like to ensure that a given package is only ever
798 published to a specific registry (for example, an internal registry),
799 then use the publishConfig dictionary described below to override the
800 registry config param at publish-time.
801
803 This is a set of config values that will be used at publish-time. It's
804 especially handy if you want to set the tag, registry or access, so
805 that you can ensure that a given package is not tagged with "latest",
806 published to the global public registry or that a scoped module is pri‐
807 vate by default.
808 Any config values can be overridden, but only "tag", "registry" and
810 "access" probably matter for the purposes of publishing.
811 See npm help 7 npm-config to see the list of config options that can be
813 overridden.
814
816 npm will default some values based on package contents.
817 · "scripts": {"start": "node server.js"} If there is a server.js file
819 in the root of your package, then npm will default the start command
820 to node server.js.
821 · "scripts":{"install": "node-gyp rebuild"} If there is a binding.gyp
823 file in the root of your package and you have not defined an install
824 or preinstall script, npm will default the install command to compile
825 using node-gyp.
826 · "contributors": [...] If there is an AUTHORS file in the root of
828 your package, npm will treat each line as a Name <email> (url) for‐
829 mat, where email and url are optional. Lines which start with a # or
830 are blank, will be ignored.
831
834 · npm help 7 semver
835 · npm help init
837 · npm help version
839 · npm help config
841 · npm help 7 config
843 · npm help help
845 · npm help install
847 · npm help publish
849 · npm help uninstall
851 October 2019 PACKAGE.JSON(5)