1PACKAGE.JSON(5) PACKAGE.JSON(5)
2
6 package.json - Specifics of npm's package.json handling
7 Description
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 ob‐
11 ject literal.
12 A lot of the behavior described in this document is affected by the
14 config settings described in npm help config.
15 name
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 names of scoped packages can begin with a dot or an underscore.
32 This is not permitted without a scope.
33 • New packages must not have uppercase letters in the name.
35 • The name ends up being part of a URL, an argument on the command
37 line, and a folder name. Therefore, the name can't contain any
38 non-URL-safe characters.
39 Some tips:
42 • Don't use the same name as a core Node module.
44 • Don't put "js" or "node" in the name. It's assumed that it's js,
46 since you're writing a package.json file, and you can specify the en‐
47 gine using the "engines" field. (See below.)
48 • The name will probably be passed as an argument to require(), so it
50 should be something short, but also reasonably descriptive.
51 • You may want to check the npm registry to see if there's something by
53 that name already, before you get too attached to it.
54 https://www.npmjs.com/
55 A name can be optionally prefixed by a scope, e.g. @myorg/mypackage.
58 See npm help scope for more detail.
59 version
61 If you plan to publish your package, the most important things in your
62 package.json are the name and version fields as they will be required.
63 The name and version together form an identifier that is assumed to be
64 completely unique. Changes to the package should come along with
65 changes to the version. If you don't plan to publish your package, the
66 name and version fields are optional.
67 Version must be parseable by node-semver
69 https://github.com/npm/node-semver, which is bundled with npm as a de‐
70 pendency. (npm install semver to use it yourself.)
71 description
73 Put a description in it. It's a string. This helps people discover
74 your package, as it's listed in npm search.
75 keywords
77 Put keywords in it. It's an array of strings. This helps people dis‐
78 cover your package as it's listed in npm search.
79 homepage
81 The url to the project homepage.
82 Example:
84 "homepage": "https://github.com/owner/project#readme"
86 bugs
88 The url to your project's issue tracker and / or the email address to
89 which issues should be reported. These are helpful for people who en‐
90 counter issues with your package.
91 It should look like this:
93 {
95 "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 license
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 {
115 "license" : "BSD-3-Clause"
116 }
117 You can check the full list of SPDX license IDs https://spdx.org/li‐
119 censes/. Ideally you should pick one that is OSI https://open‐
120 source.org/licenses/alphabetical approved.
121 If your package is licensed under multiple common licenses, use an SPDX
123 license expression syntax version 2.0 string https://spdx.dev/specifi‐
124 cations/, like this:
125 {
127 "license" : "(ISC OR GPL-3.0)"
128 }
129 If you are using a license that hasn't been assigned an SPDX identi‐
131 fier, or if you are using a custom license, use a string value like
132 this one:
133 {
135 "license" : "SEE LICENSE IN <filename>"
136 }
137 Then include a file named <filename> at the top level of the package.
139 Some old packages used license objects or a "licenses" property con‐
141 taining an array of license objects:
142 // Not valid metadata
144 {
145 "license" : {
146 "type" : "ISC",
147 "url" : "https://opensource.org/licenses/ISC"
148 }
149 }
150 // Not valid metadata
152 {
153 "licenses" : [
154 {
155 "type": "MIT",
156 "url": "https://www.opensource.org/licenses/mit-license.php"
157 },
158 {
159 "type": "Apache-2.0",
160 "url": "https://opensource.org/licenses/apache2.0.php"
161 }
162 ]
163 }
164 Those styles are now deprecated. Instead, use SPDX expressions, like
166 this:
167 {
169 "license": "ISC"
170 }
171 {
173 "license": "(MIT OR Apache-2.0)"
174 }
175 Finally, if you do not wish to grant others the right to use a private
177 or unpublished package under any terms:
178 {
180 "license": "UNLICENSED"
181 }
182 Consider also setting "private": true to prevent accidental publica‐
184 tion.
185 people fields: author, contributors
187 The "author" is one person. "contributors" is an array of people. A
188 "person" is an object with a "name" field and optionally "url" and
189 "email", like this:
190 {
192 "name" : "Barney Rubble",
193 "email" : "b@rubble.com",
194 "url" : "http://barnyrubble.tumblr.com/"
195 }
196 Or you can shorten that all into a single string, and npm will parse it
198 for you:
199 {
201 "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
202 }
203 Both email and url are optional either way.
205 npm also sets a top-level "maintainers" field with your npm user info.
207 funding
209 You can specify an object containing a URL that provides up-to-date in‐
210 formation about ways to help fund development of your package, or a
211 string URL, or an array of these:
212 {
214 "funding": {
215 "type" : "individual",
216 "url" : "http://example.com/donate"
217 },
218 "funding": {
220 "type" : "patreon",
221 "url" : "https://www.patreon.com/my-account"
222 },
223 "funding": "http://example.com/donate",
225 "funding": [
227 {
228 "type" : "individual",
229 "url" : "http://example.com/donate"
230 },
231 "http://example.com/donateAlso",
232 {
233 "type" : "patreon",
234 "url" : "https://www.patreon.com/my-account"
235 }
236 ]
237 }
238 Users can use the npm fund subcommand to list the funding URLs of all
240 dependencies of their project, direct and indirect. A shortcut to visit
241 each funding url is also available when providing the project name such
242 as: npm fund <projectname> (when there are multiple URLs, the first one
243 will be visited)
244 files
246 The optional files field is an array of file patterns that describes
247 the entries to be included when your package is installed as a depen‐
248 dency. File patterns follow a similar syntax to .gitignore, but re‐
249 versed: including a file, directory, or glob pattern (*, **/*, and
250 such) will make it so that file is included in the tarball when it's
251 packed. Omitting the field will make it default to ["*"], which means
252 it will include all files.
253 Some special files and directories are also included or excluded re‐
255 gardless of whether they exist in the files array (see below).
256 You can also provide a .npmignore file in the root of your package or
258 in subdirectories, which will keep files from being included. At the
259 root of your package it will not override the "files" field, but in
260 subdirectories it will. The .npmignore file works just like a .gitig‐
261 nore. If there is a .gitignore file, and .npmignore is missing, .gitig‐
262 nore's contents will be used instead.
263 Files included with the "package.json#files" field cannot be excluded
265 through .npmignore or .gitignore.
266 Certain files are always included, regardless of settings:
268 • package.json
270 • README
272 • LICENSE / LICENCE
274 • The file in the "main" field
276 README & LICENSE can have any case and extension.
279 Conversely, some files are always ignored:
281 • .git
283 • CVS
285 • .svn
287 • .hg
289 • .lock-wscript
291 • .wafpickle-N
293 • .*.swp
295 • .DS_Store
297 • ._*
299 • npm-debug.log
301 • .npmrc
303 • node_modules
305 • config.gypi
307 • *.orig
309 • package-lock.json (use npm help npm-shrinkwrap.json if you wish it to
311 be published)
312 main
315 The main field is a module ID that is the primary entry point to your
316 program. That is, if your package is named foo, and a user installs
317 it, and then does require("foo"), then your main module's exports ob‐
318 ject will be returned.
319 This should be a module relative to the root of your package folder.
321 For most modules, it makes the most sense to have a main script and of‐
323 ten not much else.
324 If main is not set it defaults to index.js in the package's root
326 folder.
327 browser
329 If your module is meant to be used client-side the browser field should
330 be used instead of the main field. This is helpful to hint users that
331 it might rely on primitives that aren't available in Node.js modules.
332 (e.g. window)
333 bin
335 A lot of packages have one or more executable files that they'd like to
336 install into the PATH. npm makes this pretty easy (in fact, it uses
337 this feature to install the "npm" executable.)
338 To use this, supply a bin field in your package.json which is a map of
340 command name to local file name. When this package is installed glob‐
341 ally, that file will be linked where global bins go so it is available
342 to run by name. When this package is installed as a dependency in an‐
343 other package, the file will be linked where it will be available to
344 that package either directly by npm exec or by name in other scripts
345 when invoking them via npm run-script.
346 For example, myapp could have this:
348 {
350 "bin": {
351 "myapp": "./cli.js"
352 }
353 }
354 So, when you install myapp, it'll create a symlink from the cli.js
356 script to /usr/local/bin/myapp.
357 If you have a single executable, and its name should be the name of the
359 package, then you can just supply it as a string. For example:
360 {
362 "name": "my-program",
363 "version": "1.2.5",
364 "bin": "./path/to/program"
365 }
366 would be the same as this:
368 {
370 "name": "my-program",
371 "version": "1.2.5",
372 "bin": {
373 "my-program": "./path/to/program"
374 }
375 }
376 Please make sure that your file(s) referenced in bin starts with
378 #!/usr/bin/env node, otherwise the scripts are started without the node
379 executable!
380 Note that you can also set the executable files using directories.bin
382 #directoriesbin.
383 See npm help folders for more info on executables.
385 man
387 Specify either a single file or an array of filenames to put in place
388 for the man program to find.
389 If only a single file is provided, then it's installed such that it is
391 the result from man <pkgname>, regardless of its actual filename. For
392 example:
393 {
395 "name": "foo",
396 "version": "1.2.3",
397 "description": "A packaged foo fooer for fooing foos",
398 "main": "foo.js",
399 "man": "./man/doc.1"
400 }
401 would link the ./man/doc.1 file in such that it is the target for man
403 foo
404 If the filename doesn't start with the package name, then it's pre‐
406 fixed. So, this:
407 {
409 "name": "foo",
410 "version": "1.2.3",
411 "description": "A packaged foo fooer for fooing foos",
412 "main": "foo.js",
413 "man": [
414 "./man/foo.1",
415 "./man/bar.1"
416 ]
417 }
418 will create files to do man foo and man foo-bar.
420 Man files must end with a number, and optionally a .gz suffix if they
422 are compressed. The number dictates which man section the file is in‐
423 stalled into.
424 {
426 "name": "foo",
427 "version": "1.2.3",
428 "description": "A packaged foo fooer for fooing foos",
429 "main": "foo.js",
430 "man": [
431 "./man/foo.1",
432 "./man/foo.2"
433 ]
434 }
435 will create entries for man foo and man 2 foo
437 directories
439 The CommonJS Packages http://wiki.commonjs.org/wiki/Packages/1.0 spec
440 details a few ways that you can indicate the structure of your package
441 using a directories object. If you look at npm's package.json
442 https://registry.npmjs.org/npm/latest, you'll see that it has directo‐
443 ries for doc, lib, and man.
444 In the future, this information may be used in other creative ways.
446 directories.bin
448 If you specify a bin directory in directories.bin, all the files in
449 that folder will be added.
450 Because of the way the bin directive works, specifying both a bin path
452 and setting directories.bin is an error. If you want to specify indi‐
453 vidual files, use bin, and for all the files in an existing bin direc‐
454 tory, use directories.bin.
455 directories.man
457 A folder that is full of man pages. Sugar to generate a "man" array by
458 walking the folder.
459 repository
461 Specify the place where your code lives. This is helpful for people who
462 want to contribute. If the git repo is on GitHub, then the npm docs
463 command will be able to find you.
464 Do it like this:
466 {
468 "repository": {
469 "type": "git",
470 "url": "https://github.com/npm/cli.git"
471 }
472 }
473 The URL should be a publicly available (perhaps read-only) url that can
475 be handed directly to a VCS program without any modification. It
476 should not be a url to an html project page that you put in your
477 browser. It's for computers.
478 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use
480 the same shortcut syntax you use for npm install:
481 {
483 "repository": "npm/npm",
484 "repository": "github:user/repo",
486 "repository": "gist:11081aaa281",
488 "repository": "bitbucket:user/repo",
490 "repository": "gitlab:user/repo"
492 }
493 If the package.json for your package is not in the root directory (for
495 example if it is part of a monorepo), you can specify the directory in
496 which it lives:
497 {
499 "repository": {
500 "type": "git",
501 "url": "https://github.com/facebook/react.git",
502 "directory": "packages/react-dom"
503 }
504 }
505 scripts
507 The "scripts" property is a dictionary containing script commands that
508 are run at various times in the lifecycle of your package. The key is
509 the lifecycle event, and the value is the command to run at that point.
510 See npm help scripts to find out more about writing package scripts.
512 config
514 A "config" object can be used to set configuration parameters used in
515 package scripts that persist across upgrades. For instance, if a pack‐
516 age had the following:
517 {
519 "name": "foo",
520 "config": {
521 "port": "8080"
522 }
523 }
524 It could also have a "start" command that referenced the npm_pack‐
526 age_config_port environment variable.
527 dependencies
529 Dependencies are specified in a simple object that maps a package name
530 to a version range. The version range is a string which has one or more
531 space-separated descriptors. Dependencies can also be identified with
532 a tarball or git URL.
533 Please do not put test harnesses or transpilers or other "development"
535 time tools in your dependencies object. See devDependencies, below.
536 See semver https://github.com/npm/node-semver#versions for more details
538 about specifying version ranges.
539 • version Must match version exactly
541 • >version Must be greater than version
543 • >=version etc
545 • <version
547 • <=version
549 • ~version "Approximately equivalent to version" See semver
551 https://github.com/npm/node-semver#versions
552 • ^version "Compatible with version" See semver
554 https://github.com/npm/node-semver#versions
555 • 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
557 • http://... See 'URLs as Dependencies' below
559 • * Matches any version
561 • "" (just an empty string) Same as *
563 • version1 - version2 Same as >=version1 <=version2.
565 • range1 || range2 Passes if either range1 or range2 are satisfied.
567 • git... See 'Git URLs as Dependencies' below
569 • user/repo See 'GitHub URLs' below
571 • tag A specific version tagged and published as tag See npm help npm
573 dist-tag
574 • path/path/path See Local Paths #local-paths below
576 For example, these are all valid:
579 {
581 "dependencies": {
582 "foo": "1.0.0 - 2.9999.9999",
583 "bar": ">=1.0.2 <2.1.2",
584 "baz": ">1.0.2 <=2.3.4",
585 "boo": "2.0.1",
586 "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
587 "asd": "http://asdf.com/asdf.tar.gz",
588 "til": "~1.2",
589 "elf": "~1.2.3",
590 "two": "2.x",
591 "thr": "3.3.x",
592 "lat": "latest",
593 "dyl": "file:../dyl"
594 }
595 }
596 URLs as Dependencies
598 You may specify a tarball URL in place of a version range.
599 This tarball will be downloaded and installed locally to your package
601 at install time.
602 Git URLs as Dependencies
604 Git urls are of the form:
605 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
607 <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
609 If #<commit-ish> is provided, it will be used to clone exactly that
611 commit. If the commit-ish has the format #semver:<semver>, <semver> can
612 be any valid semver range or exact version, and npm will look for any
613 tags or refs matching that range in the remote repository, much as it
614 would for a registry dependency. If neither #<commit-ish> or
615 #semver:<semver> is specified, then the default branch is used.
616 Examples:
618 git+ssh://git@github.com:npm/cli.git#v1.0.27
620 git+ssh://git@github.com:npm/cli#semver:^5.0
621 git+https://isaacs@github.com/npm/cli.git
622 git://github.com/npm/cli.git#v1.0.27
623 When installing from a git repository, the presence of certain fields
625 in the package.json will cause npm to believe it needs to perform a
626 build. To do so your repository will be cloned into a temporary direc‐
627 tory, all of its deps installed, relevant scripts run, and the result‐
628 ing directory packed and installed.
629 This flow will occur if your git dependency uses workspaces, or if any
631 of the following scripts are present:
632 • build
634 • prepare
636 • prepack
638 • preinstall
640 • install
642 • postinstall
644 If your git repository includes pre-built artifacts, you will likely
647 want to make sure that none of the above scripts are defined, or your
648 dependency will be rebuilt for every installation.
649 GitHub URLs
651 As of version 1.1.65, you can refer to GitHub urls as just "foo":
652 "user/foo-project". Just as with git URLs, a commit-ish suffix can be
653 included. For example:
654 {
656 "name": "foo",
657 "version": "0.0.0",
658 "dependencies": {
659 "express": "expressjs/express",
660 "mocha": "mochajs/mocha#4727d357ea",
661 "module": "user/repo#feature\/branch"
662 }
663 }
664 Local Paths
666 As of version 2.0.0 you can provide a path to a local directory that
667 contains a package. Local paths can be saved using npm install -S or
668 npm install --save, using any of these forms:
669 ../foo/bar
671 ~/foo/bar
672 ./foo/bar
673 /foo/bar
674 in which case they will be normalized to a relative path and added to
676 your package.json. For example:
677 {
679 "name": "baz",
680 "dependencies": {
681 "bar": "file:../foo/bar"
682 }
683 }
684 This feature is helpful for local offline development and creating
686 tests that require npm installing where you don't want to hit an exter‐
687 nal server, but should not be used when publishing packages to the pub‐
688 lic registry.
689 note: Packages linked by local path will not have their own dependen‐
691 cies installed when npm install is ran in this case. You must run npm
692 install from inside the local path itself.
693 devDependencies
695 If someone is planning on downloading and using your module in their
696 program, then they probably don't want or need to download and build
697 the external test or documentation framework that you use.
698 In this case, it's best to map these additional items in a devDependen‐
700 cies object.
701 These things will be installed when doing npm link or npm install from
703 the root of a package, and can be managed like any other npm configura‐
704 tion param. See npm help config for more on the topic.
705 For build steps that are not platform-specific, such as compiling Cof‐
707 feeScript or other languages to JavaScript, use the prepare script to
708 do this, and make the required package a devDependency.
709 For example:
711 {
713 "name": "ethopia-waza",
714 "description": "a delightfully fruity coffee varietal",
715 "version": "1.2.3",
716 "devDependencies": {
717 "coffee-script": "~1.6.3"
718 },
719 "scripts": {
720 "prepare": "coffee -o lib/ -c src/waza.coffee"
721 },
722 "main": "lib/waza.js"
723 }
724 The prepare script will be run before publishing, so that users can
726 consume the functionality without requiring them to compile it them‐
727 selves. In dev mode (ie, locally running npm install), it'll run this
728 script as well, so that you can test it easily.
729 peerDependencies
731 In some cases, you want to express the compatibility of your package
732 with a host tool or library, while not necessarily doing a require of
733 this host. This is usually referred to as a plugin. Notably, your mod‐
734 ule may be exposing a specific interface, expected and specified by the
735 host documentation.
736 For example:
738 {
740 "name": "tea-latte",
741 "version": "1.3.5",
742 "peerDependencies": {
743 "tea": "2.x"
744 }
745 }
746 This ensures your package tea-latte can be installed along with the
748 second major version of the host package tea only. npm install
749 tea-latte could possibly yield the following dependency graph:
750 ├── tea-latte@1.3.5
752 └── tea@2.2.0
753 In npm versions 3 through 6, peerDependencies were not automatically
755 installed, and would raise a warning if an invalid version of the peer
756 dependency was found in the tree. As of npm v7, peerDependencies are
757 installed by default.
758 Trying to install another plugin with a conflicting requirement may
760 cause an error if the tree cannot be resolved correctly. For this rea‐
761 son, make sure your plugin requirement is as broad as possible, and not
762 to lock it down to specific patch versions.
763 Assuming the host complies with semver https://semver.org/, only
765 changes in the host package's major version will break your plugin.
766 Thus, if you've worked with every 1.x version of the host package, use
767 "^1.0" or "1.x" to express this. If you depend on features introduced
768 in 1.5.2, use "^1.5.2".
769 peerDependenciesMeta
771 When a user installs your package, npm will emit warnings if packages
772 specified in peerDependencies are not already installed. The peerDepen‐
773 denciesMeta field serves to provide npm more information on how your
774 peer dependencies are to be used. Specifically, it allows peer depen‐
775 dencies to be marked as optional.
776 For example:
778 {
780 "name": "tea-latte",
781 "version": "1.3.5",
782 "peerDependencies": {
783 "tea": "2.x",
784 "soy-milk": "1.2"
785 },
786 "peerDependenciesMeta": {
787 "soy-milk": {
788 "optional": true
789 }
790 }
791 }
792 Marking a peer dependency as optional ensures npm will not emit a warn‐
794 ing if the soy-milk package is not installed on the host. This allows
795 you to integrate and interact with a variety of host packages without
796 requiring all of them to be installed.
797 bundleDependencies
799 This defines an array of package names that will be bundled when pub‐
800 lishing the package.
801 In cases where you need to preserve npm packages locally or have them
803 available through a single file download, you can bundle the packages
804 in a tarball file by specifying the package names in the bundleDepen‐
805 dencies array and executing npm pack.
806 For example:
808 If we define a package.json like this:
810 {
812 "name": "awesome-web-framework",
813 "version": "1.0.0",
814 "bundleDependencies": [
815 "renderized",
816 "super-streams"
817 ]
818 }
819 we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack.
821 This file contains the dependencies renderized and super-streams which
822 can be installed in a new project by executing npm install awe‐
823 some-web-framework-1.0.0.tgz. Note that the package names do not in‐
824 clude any versions, as that information is specified in dependencies.
825 If this is spelled "bundledDependencies", then that is also honored.
827 Alternatively, "bundleDependencies" can be defined as a boolean value.
829 A value of true will bundle all dependencies, a value of false will
830 bundle none.
831 optionalDependencies
833 If a dependency can be used, but you would like npm to proceed if it
834 cannot be found or fails to install, then you may put it in the option‐
835 alDependencies object. This is a map of package name to version or
836 url, just like the dependencies object. The difference is that build
837 failures do not cause installation to fail. Running npm install
838 --omit=optional will prevent these dependencies from being installed.
839 It is still your program's responsibility to handle the lack of the de‐
841 pendency. For example, something like this:
842 try {
844 var foo = require('foo')
845 var fooVersion = require('foo/package.json').version
846 } catch (er) {
847 foo = null
848 }
849 if ( notGoodFooVersion(fooVersion) ) {
850 foo = null
851 }
852 // .. then later in your program ..
854 if (foo) {
856 foo.doFooThings()
857 }
858 Entries in optionalDependencies will override entries of the same name
860 in dependencies, so it's usually best to only put in one place.
861 overrides
863 If you need to make specific changes to dependencies of your dependen‐
864 cies, for example replacing the version of a dependency with a known
865 security issue, replacing an existing dependency with a fork, or making
866 sure that the same version of a package is used everywhere, then you
867 may add an override.
868 Overrides provide a way to replace a package in your dependency tree
870 with another version, or another package entirely. These changes can be
871 scoped as specific or as vague as desired.
872 To make sure the package foo is always installed as version 1.0.0 no
874 matter what version your dependencies rely on:
875 {
877 "overrides": {
878 "foo": "1.0.0"
879 }
880 }
881 The above is a short hand notation, the full object form can be used to
883 allow overriding a package itself as well as a child of the package.
884 This will cause foo to always be 1.0.0 while also making bar at any
885 depth beyond foo also 1.0.0:
886 {
888 "overrides": {
889 "foo": {
890 ".": "1.0.0",
891 "bar": "1.0.0"
892 }
893 }
894 }
895 To only override foo to be 1.0.0 when it's a child (or grandchild, or
897 great grandchild, etc) of the package bar:
898 {
900 "overrides": {
901 "bar": {
902 "foo": "1.0.0"
903 }
904 }
905 }
906 Keys can be nested to any arbitrary length. To override foo only when
908 it's a child of bar and only when bar is a child of baz:
909 {
911 "overrides": {
912 "baz": {
913 "bar": {
914 "foo": "1.0.0"
915 }
916 }
917 }
918 }
919 The key of an override can also include a version, or range of ver‐
921 sions. To override foo to 1.0.0, but only when it's a child of
922 bar@2.0.0:
923 {
925 "overrides": {
926 "bar@2.0.0": {
927 "foo": "1.0.0"
928 }
929 }
930 }
931 You may not set an override for a package that you directly depend on
933 unless both the dependency and the override itself share the exact same
934 spec. To make this limitation easier to deal with, overrides may also
935 be defined as a reference to a spec for a direct dependency by prefix‐
936 ing the name of the package you wish the version to match with a $.
937 {
939 "dependencies": {
940 "foo": "^1.0.0"
941 },
942 "overrides": {
943 // BAD, will throw an EOVERRIDE error
944 // "foo": "^2.0.0"
945 // GOOD, specs match so override is allowed
946 // "foo": "^1.0.0"
947 // BEST, the override is defined as a reference to the dependency
948 "foo": "$foo",
949 // the referenced package does not need to match the overridden one
950 "bar": "$foo"
951 }
952 }
953 engines
955 You can specify the version of node that your stuff works on:
956 {
958 "engines": {
959 "node": ">=0.10.3 <15"
960 }
961 }
962 And, like with dependencies, if you don't specify the version (or if
964 you specify "*" as the version), then any version of node will do.
965 You can also use the "engines" field to specify which versions of npm
967 are capable of properly installing your program. For example:
968 {
970 "engines": {
971 "npm": "~1.0.20"
972 }
973 }
974 Unless the user has set the engine-strict config flag, this field is
976 advisory only and will only produce warnings when your package is in‐
977 stalled as a dependency.
978 os
980 You can specify which operating systems your module will run on:
981 {
983 "os": [
984 "darwin",
985 "linux"
986 ]
987 }
988 You can also block instead of allowing operating systems, just prepend
990 the blocked os with a '!':
991 {
993 "os": [
994 "!win32"
995 ]
996 }
997 The host operating system is determined by process.platform
999 It is allowed to both block and allow an item, although there isn't any
1001 good reason to do this.
1002 cpu
1004 If your code only runs on certain cpu architectures, you can specify
1005 which ones.
1006 {
1008 "cpu": [
1009 "x64",
1010 "ia32"
1011 ]
1012 }
1013 Like the os option, you can also block architectures:
1015 {
1017 "cpu": [
1018 "!arm",
1019 "!mips"
1020 ]
1021 }
1022 The host architecture is determined by process.arch
1024 private
1026 If you set "private": true in your package.json, then npm will refuse
1027 to publish it.
1028 This is a way to prevent accidental publication of private reposito‐
1030 ries. If you would like to ensure that a given package is only ever
1031 published to a specific registry (for example, an internal registry),
1032 then use the publishConfig dictionary described below to override the
1033 registry config param at publish-time.
1034 publishConfig
1036 This is a set of config values that will be used at publish-time. It's
1037 especially handy if you want to set the tag, registry or access, so
1038 that you can ensure that a given package is not tagged with "latest",
1039 published to the global public registry or that a scoped module is pri‐
1040 vate by default.
1041 See npm help config to see the list of config options that can be over‐
1043 ridden.
1044 workspaces
1046 The optional workspaces field is an array of file patterns that de‐
1047 scribes locations within the local file system that the install client
1048 should look up to find each npm help workspace that needs to be sym‐
1049 linked to the top level node_modules folder.
1050 It can describe either the direct paths of the folders to be used as
1052 workspaces or it can define globs that will resolve to these same fold‐
1053 ers.
1054 In the following example, all folders located inside the folder ./pack‐
1056 ages will be treated as workspaces as long as they have valid pack‐
1057 age.json files inside them:
1058 {
1060 "name": "workspace-example",
1061 "workspaces": [
1062 "./packages/*"
1063 ]
1064 }
1065 See npm help workspaces for more examples.
1067 DEFAULT VALUES
1069 npm will default some values based on package contents.
1070 • "scripts": {"start": "node server.js"} If there is a server.js file
1072 in the root of your package, then npm will default the start command
1073 to node server.js.
1074 • "scripts":{"install": "node-gyp rebuild"} If there is a binding.gyp
1076 file in the root of your package and you have not defined an install
1077 or preinstall script, npm will default the install command to compile
1078 using node-gyp.
1079 • "contributors": [...] If there is an AUTHORS file in the root of
1081 your package, npm will treat each line as a Name <email> (url) for‐
1082 mat, where email and url are optional. Lines which start with a # or
1083 are blank, will be ignored.
1084 SEE ALSO
1087 • semver https://github.com/npm/node-semver#versions
1088 • npm help workspaces
1090 • npm help init
1092 • npm help version
1094 • npm help config
1096 • npm help help
1098 • npm help install
1100 • npm help publish
1102 • npm help uninstall
1104 September 2022 PACKAGE.JSON(5)