1PACKAGE.JSON(5)                                                PACKAGE.JSON(5)
2
3
4

NAME

6       package.json - Specifics of npm's package.json handling
7
8   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
13       A  lot  of  the  behavior described in this document is affected by the
14       config settings described in npm help config.
15
16   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
24       The name is what your thing is called.
25
26       Some rules:
27
28       • The  name must be less than or equal to 214 characters. This includes
29         the scope for scoped packages.
30
31       • The names of scoped packages can begin with a dot or  an  underscore.
32         This is not permitted without a scope.
33
34       • New packages must not have uppercase letters in the name.
35
36       • 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
40
41       Some tips:
42
43       • Don't use the same name as a core Node module.
44
45       • 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
49       • The  name  will probably be passed as an argument to require(), so it
50         should be something short, but also reasonably descriptive.
51
52       • 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
56
57       A name can be optionally prefixed by a  scope,  e.g.  @myorg/mypackage.
58       See npm help scope for more detail.
59
60   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
68       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
72   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
76   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
80   homepage
81       The url to the project homepage.
82
83       Example:
84
85         "homepage": "https://github.com/owner/project#readme"
86
87   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
92       It should look like this:
93
94         {
95           "url" : "https://github.com/owner/project/issues",
96           "email" : "project@hostname.com"
97         }
98
99       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
103       If a url is provided, it will be used by the npm bugs command.
104
105   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
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
112       this:
113
114         {
115           "license" : "BSD-3-Clause"
116         }
117
118       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
122       If your package is licensed under multiple common licenses, use an SPDX
123       license       expression       syntax      version      2.0      string
124       https://www.npmjs.com/package/spdx, like this:
125
126         {
127           "license" : "(ISC OR GPL-3.0)"
128         }
129
130       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
134         {
135           "license" : "SEE LICENSE IN <filename>"
136         }
137
138       Then include a file named <filename> at the top level of the package.
139
140       Some old packages used license objects or a  "licenses"  property  con‐
141       taining an array of license objects:
142
143         // Not valid metadata
144         {
145           "license" : {
146             "type" : "ISC",
147             "url" : "https://opensource.org/licenses/ISC"
148           }
149         }
150
151         // 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
165       Those  styles  are  now deprecated. Instead, use SPDX expressions, like
166       this:
167
168         {
169           "license": "ISC"
170         }
171
172         {
173           "license": "(MIT OR Apache-2.0)"
174         }
175
176       Finally, if you do not wish to grant others the right to use a  private
177       or unpublished package under any terms:
178
179         {
180           "license": "UNLICENSED"
181         }
182
183       Consider  also  setting  "private": true to prevent accidental publica‐
184       tion.
185
186   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
191         {
192           "name" : "Barney Rubble",
193           "email" : "b@rubble.com",
194           "url" : "http://barnyrubble.tumblr.com/"
195         }
196
197       Or you can shorten that all into a single string, and npm will parse it
198       for you:
199
200         {
201           "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
202         }
203
204       Both email and url are optional either way.
205
206       npm also sets a top-level "maintainers" field with your npm user info.
207
208   funding
209       You  can  specify  an object containing an URL that provides up-to-date
210       information about ways to help fund development of your package,  or  a
211       string URL, or an array of these:
212
213         {
214           "funding": {
215             "type" : "individual",
216             "url" : "http://example.com/donate"
217           },
218
219           "funding": {
220             "type" : "patreon",
221             "url" : "https://www.patreon.com/my-account"
222           },
223
224           "funding": "http://example.com/donate",
225
226           "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
239       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
245   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
254       Some  special  files  and directories are also included or excluded re‐
255       gardless of whether they exist in the files array (see below).
256
257       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
264       Files  included  with the "package.json#files" field cannot be excluded
265       through .npmignore or .gitignore.
266
267       Certain files are always included, regardless of settings:
268
269package.json
270
271README
272
273LICENSE / LICENCE
274
275       • The file in the "main" field
276
277
278       README & LICENSE can have any case and extension.
279
280       Conversely, some files are always ignored:
281
282.git
283
284CVS
285
286.svn
287
288.hg
289
290.lock-wscript
291
292.wafpickle-N
293
294.*.swp
295
296.DS_Store
297
298._*
299
300npm-debug.log
301
302.npmrc
303
304node_modules
305
306config.gypi
307
308*.orig
309
310package-lock.json (use npm help npm-shrinkwrap.json if you wish it to
311         be published)
312
313
314   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
320       This should be a module relative to the root of your package folder.
321
322       For most modules, it makes the most sense to have a main script and of‐
323       ten not much else.
324
325       If main is not set it defaults to index.js in the packages root folder.
326
327   browser
328       If your module is meant to be used client-side the browser field should
329       be used instead of the main field. This is helpful to hint  users  that
330       it  might  rely on primitives that aren't available in Node.js modules.
331       (e.g.  window)
332
333   bin
334       A lot of packages have one or more executable files that they'd like to
335       install  into  the  PATH.  npm makes this pretty easy (in fact, it uses
336       this feature to install the "npm" executable.)
337
338       To use this, supply a bin field in your package.json which is a map  of
339       command  name  to local file name. When this package is installed glob‐
340       ally, that file will be linked where global bins go so it is  available
341       to  run by name.  When this package is installed as a dependency in an‐
342       other package, the file will be linked where it will  be  available  to
343       that  package  either  directly by npm exec or by name in other scripts
344       when invoking them via npm run-script.
345
346       For example, myapp could have this:
347
348         {
349           "bin": {
350             "myapp": "./cli.js"
351           }
352         }
353
354       So, when you install myapp, it'll create  a  symlink  from  the  cli.js
355       script to /usr/local/bin/myapp.
356
357       If you have a single executable, and its name should be the name of the
358       package, then you can just supply it as a string.  For example:
359
360         {
361           "name": "my-program",
362           "version": "1.2.5",
363           "bin": "./path/to/program"
364         }
365
366       would be the same as this:
367
368         {
369           "name": "my-program",
370           "version": "1.2.5",
371           "bin": {
372             "my-program": "./path/to/program"
373           }
374         }
375
376       Please make sure that  your  file(s)  referenced  in  bin  starts  with
377       #!/usr/bin/env node, otherwise the scripts are started without the node
378       executable!
379
380       Note that you can also set the executable files  using  directories.bin
381       #directoriesbin.
382
383       See npm help folders for more info on executables.
384
385   man
386       Specify  either  a single file or an array of filenames to put in place
387       for the man program to find.
388
389       If only a single file is provided, then it's installed such that it  is
390       the  result from man <pkgname>, regardless of its actual filename.  For
391       example:
392
393         {
394           "name": "foo",
395           "version": "1.2.3",
396           "description": "A packaged foo fooer for fooing foos",
397           "main": "foo.js",
398           "man": "./man/doc.1"
399         }
400
401       would link the ./man/doc.1 file in such that it is the target  for  man
402       foo
403
404       If  the  filename  doesn't  start with the package name, then it's pre‐
405       fixed.  So, this:
406
407         {
408           "name": "foo",
409           "version": "1.2.3",
410           "description": "A packaged foo fooer for fooing foos",
411           "main": "foo.js",
412           "man": [
413             "./man/foo.1",
414             "./man/bar.1"
415           ]
416         }
417
418       will create files to do man foo and man foo-bar.
419
420       Man files must end with a number, and optionally a .gz suffix  if  they
421       are  compressed.  The number dictates which man section the file is in‐
422       stalled into.
423
424         {
425           "name": "foo",
426           "version": "1.2.3",
427           "description": "A packaged foo fooer for fooing foos",
428           "main": "foo.js",
429           "man": [
430             "./man/foo.1",
431             "./man/foo.2"
432           ]
433         }
434
435       will create entries for man foo and man 2 foo
436
437   directories
438       The CommonJS Packages  http://wiki.commonjs.org/wiki/Packages/1.0  spec
439       details  a few ways that you can indicate the structure of your package
440       using  a  directories  object.  If  you  look  at  npm's   package.json
441       https://registry.npmjs.org/npm/latest,  you'll see that it has directo‐
442       ries for doc, lib, and man.
443
444       In the future, this information may be used in other creative ways.
445
446   directories.bin
447       If you specify a bin directory in directories.bin,  all  the  files  in
448       that folder will be added.
449
450       Because  of the way the bin directive works, specifying both a bin path
451       and setting directories.bin is an error. If you want to  specify  indi‐
452       vidual  files, use bin, and for all the files in an existing bin direc‐
453       tory, use directories.bin.
454
455   directories.man
456       A folder that is full of man pages.  Sugar to generate a "man" array by
457       walking the folder.
458
459   repository
460       Specify the place where your code lives. This is helpful for people who
461       want to contribute.  If the git repo is on GitHub, then  the  npm  docs
462       command will be able to find you.
463
464       Do it like this:
465
466         {
467           "repository": {
468             "type": "git",
469             "url": "https://github.com/npm/cli.git"
470           }
471         }
472
473       The URL should be a publicly available (perhaps read-only) url that can
474       be handed directly to a  VCS  program  without  any  modification.   It
475       should  not  be  a  url  to  an  html project page that you put in your
476       browser.  It's for computers.
477
478       For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can  use
479       the same shortcut syntax you use for npm install:
480
481         {
482           "repository": "npm/npm",
483
484           "repository": "github:user/repo",
485
486           "repository": "gist:11081aaa281",
487
488           "repository": "bitbucket:user/repo",
489
490           "repository": "gitlab:user/repo"
491         }
492
493       If  the package.json for your package is not in the root directory (for
494       example if it is part of a monorepo), you can specify the directory  in
495       which it lives:
496
497         {
498           "repository": {
499             "type": "git",
500             "url": "https://github.com/facebook/react.git",
501             "directory": "packages/react-dom"
502           }
503         }
504
505   scripts
506       The  "scripts" property is a dictionary containing script commands that
507       are run at various times in the lifecycle of your package.  The key  is
508       the lifecycle event, and the value is the command to run at that point.
509
510       See npm help scripts to find out more about writing package scripts.
511
512   config
513       A  "config"  object can be used to set configuration parameters used in
514       package scripts that persist across upgrades.  For instance, if a pack‐
515       age had the following:
516
517         {
518           "name": "foo",
519           "config": {
520             "port": "8080"
521           }
522         }
523
524       It  could  also  have  a  "start" command that referenced the npm_pack‐
525       age_config_port environment variable.
526
527   dependencies
528       Dependencies are specified in a simple object that maps a package  name
529       to a version range. The version range is a string which has one or more
530       space-separated descriptors.  Dependencies can also be identified  with
531       a tarball or git URL.
532
533       Please  do not put test harnesses or transpilers or other "development"
534       time tools in your dependencies object.  See devDependencies, below.
535
536       See semver https://github.com/npm/node-semver#versions for more details
537       about specifying version ranges.
538
539version Must match version exactly
540
541>version Must be greater than version
542
543>=version etc
544
545<version
546
547<=version
548
549~version   "Approximately   equivalent   to   version"    See  semver
550         https://github.com/npm/node-semver#versions
551
552^version     "Compatible     with      version"       See      semver
553         https://github.com/npm/node-semver#versions
554
5551.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
556
557http://... See 'URLs as Dependencies' below
558
559* Matches any version
560
561"" (just an empty string) Same as *
562
563version1 - version2 Same as >=version1 <=version2.
564
565range1 || range2 Passes if either range1 or range2 are satisfied.
566
567git... See 'Git URLs as Dependencies' below
568
569user/repo See 'GitHub URLs' below
570
571tag  A specific version tagged and published as tag  See npm help npm
572         dist-tag
573
574path/path/path See Local Paths #local-paths below
575
576
577       For example, these are all valid:
578
579         {
580           "dependencies": {
581             "foo": "1.0.0 - 2.9999.9999",
582             "bar": ">=1.0.2 <2.1.2",
583             "baz": ">1.0.2 <=2.3.4",
584             "boo": "2.0.1",
585             "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
586             "asd": "http://asdf.com/asdf.tar.gz",
587             "til": "~1.2",
588             "elf": "~1.2.3",
589             "two": "2.x",
590             "thr": "3.3.x",
591             "lat": "latest",
592             "dyl": "file:../dyl"
593           }
594         }
595
596   URLs as Dependencies
597       You may specify a tarball URL in place of a version range.
598
599       This tarball will be downloaded and installed locally to  your  package
600       at install time.
601
602   Git URLs as Dependencies
603       Git urls are of the form:
604
605         <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
606
607       <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
608
609       If  #<commit-ish>  is  provided,  it will be used to clone exactly that
610       commit. If the commit-ish has the format #semver:<semver>, <semver> can
611       be  any  valid semver range or exact version, and npm will look for any
612       tags or refs matching that range in the remote repository, much  as  it
613       would   for   a   registry  dependency.  If  neither  #<commit-ish>  or
614       #semver:<semver> is specified, then master is used.
615
616       Examples:
617
618         git+ssh://git@github.com:npm/cli.git#v1.0.27
619         git+ssh://git@github.com:npm/cli#semver:^5.0
620         git+https://isaacs@github.com/npm/cli.git
621         git://github.com/npm/cli.git#v1.0.27
622
623   GitHub URLs
624       As of version 1.1.65, you can refer  to  GitHub  urls  as  just  "foo":
625       "user/foo-project".   Just as with git URLs, a commit-ish suffix can be
626       included.  For example:
627
628         {
629           "name": "foo",
630           "version": "0.0.0",
631           "dependencies": {
632             "express": "expressjs/express",
633             "mocha": "mochajs/mocha#4727d357ea",
634             "module": "user/repo#feature\/branch"
635           }
636         }
637
638   Local Paths
639       As of version 2.0.0 you can provide a path to a  local  directory  that
640       contains  a  package.  Local paths can be saved using npm install -S or
641       npm install --save, using any of these forms:
642
643         ../foo/bar
644         ~/foo/bar
645         ./foo/bar
646         /foo/bar
647
648       in which case they will be normalized to a relative path and  added  to
649       your package.json. For example:
650
651         {
652           "name": "baz",
653           "dependencies": {
654             "bar": "file:../foo/bar"
655           }
656         }
657
658       This  feature  is  helpful  for  local offline development and creating
659       tests that require npm installing where you don't want to hit an exter‐
660       nal server, but should not be used when publishing packages to the pub‐
661       lic registry.
662
663   devDependencies
664       If someone is planning on downloading and using your  module  in  their
665       program,  then  they  probably don't want or need to download and build
666       the external test or documentation framework that you use.
667
668       In this case, it's best to map these additional items in a devDependen‐
669       cies object.
670
671       These  things will be installed when doing npm link or npm install from
672       the root of a package, and can be managed like any other npm configura‐
673       tion param.  See npm help config for more on the topic.
674
675       For  build steps that are not platform-specific, such as compiling Cof‐
676       feeScript or other languages to JavaScript, use the prepare  script  to
677       do this, and make the required package a devDependency.
678
679       For example:
680
681         {
682           "name": "ethopia-waza",
683           "description": "a delightfully fruity coffee varietal",
684           "version": "1.2.3",
685           "devDependencies": {
686             "coffee-script": "~1.6.3"
687           },
688           "scripts": {
689             "prepare": "coffee -o lib/ -c src/waza.coffee"
690           },
691           "main": "lib/waza.js"
692         }
693
694       The  prepare  script  will  be run before publishing, so that users can
695       consume the functionality without requiring them to  compile  it  them‐
696       selves.   In dev mode (ie, locally running npm install), it'll run this
697       script as well, so that you can test it easily.
698
699   peerDependencies
700       In some cases, you want to express the compatibility  of  your  package
701       with  a  host tool or library, while not necessarily doing a require of
702       this host.  This is usually referred to as a plugin. Notably, your mod‐
703       ule may be exposing a specific interface, expected and specified by the
704       host documentation.
705
706       For example:
707
708         {
709           "name": "tea-latte",
710           "version": "1.3.5",
711           "peerDependencies": {
712             "tea": "2.x"
713           }
714         }
715
716       This ensures your package tea-latte can be  installed  along  with  the
717       second  major  version  of  the  host  package  tea  only.  npm install
718       tea-latte could possibly yield the following dependency graph:
719
720         ├── tea-latte@1.3.5
721         └── tea@2.2.0
722
723       In npm versions 3 through 6, peerDependencies  were  not  automatically
724       installed,  and would raise a warning if an invalid version of the peer
725       dependency was found in the tree.  As of npm v7,  peerDependencies  are
726       installed by default.
727
728       Trying  to  install  another  plugin with a conflicting requirement may
729       cause an error if the tree cannot be resolved correctly. For this  rea‐
730       son, make sure your plugin requirement is as broad as possible, and not
731       to lock it down to specific patch versions.
732
733       Assuming  the  host  complies  with  semver  https://semver.org/,  only
734       changes  in  the  host  package's major version will break your plugin.
735       Thus, if you've worked with every 1.x version of the host package,  use
736       "^1.0"  or  "1.x" to express this. If you depend on features introduced
737       in 1.5.2, use "^1.5.2".
738
739   peerDependenciesMeta
740       When a user installs your package, npm will emit warnings  if  packages
741       specified in peerDependencies are not already installed. The peerDepen‐
742       denciesMeta field serves to provide npm more information  on  how  your
743       peer  dependencies  are to be used. Specifically, it allows peer depen‐
744       dencies to be marked as optional.
745
746       For example:
747
748         {
749           "name": "tea-latte",
750           "version": "1.3.5",
751           "peerDependencies": {
752             "tea": "2.x",
753             "soy-milk": "1.2"
754           },
755           "peerDependenciesMeta": {
756             "soy-milk": {
757               "optional": true
758             }
759           }
760         }
761
762       Marking a peer dependency as optional ensures npm will not emit a warn‐
763       ing  if  the soy-milk package is not installed on the host. This allows
764       you to integrate and interact with a variety of host  packages  without
765       requiring all of them to be installed.
766
767   bundledDependencies
768       This  defines  an array of package names that will be bundled when pub‐
769       lishing the package.
770
771       In cases where you need to preserve npm packages locally or  have  them
772       available  through  a single file download, you can bundle the packages
773       in a tarball file by specifying the package names in the  bundledDepen‐
774       dencies array and executing npm pack.
775
776       For example:
777
778       If we define a package.json like this:
779
780         {
781           "name": "awesome-web-framework",
782           "version": "1.0.0",
783           "bundledDependencies": [
784             "renderized",
785             "super-streams"
786           ]
787         }
788
789       we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack.
790       This file contains the dependencies renderized and super-streams  which
791       can  be  installed  in  a  new  project  by  executing npm install awe‐
792       some-web-framework-1.0.0.tgz.  Note that the package names do  not  in‐
793       clude any versions, as that information is specified in dependencies.
794
795       If this is spelled "bundleDependencies", then that is also honored.
796
797   optionalDependencies
798       If  a  dependency  can be used, but you would like npm to proceed if it
799       cannot be found or fails to install, then you may put it in the option‐
800       alDependencies  object.   This  is  a map of package name to version or
801       url, just like the dependencies object.  The difference is  that  build
802       failures  do  not  cause  installation  to  fail.   Running npm install
803       --no-optional will prevent these dependencies from being installed.
804
805       It is still your program's responsibility to handle the lack of the de‐
806       pendency.  For example, something like this:
807
808         try {
809           var foo = require('foo')
810           var fooVersion = require('foo/package.json').version
811         } catch (er) {
812           foo = null
813         }
814         if ( notGoodFooVersion(fooVersion) ) {
815           foo = null
816         }
817
818         // .. then later in your program ..
819
820         if (foo) {
821           foo.doFooThings()
822         }
823
824       Entries  in optionalDependencies will override entries of the same name
825       in dependencies, so it's usually best to only put in one place.
826
827   overrides
828       If you need to make specific changes to dependencies of your  dependen‐
829       cies,  for  example  replacing the version of a dependency with a known
830       security issue, replacing an existing dependency with a fork, or making
831       sure  that  the  same version of a package is used everywhere, then you
832       may add an override.
833
834       Overrides provide a way to replace a package in  your  dependency  tree
835       with another version, or another package entirely. These changes can be
836       scoped as specific or as vague as desired.
837
838       To make sure the package foo is always installed as  version  1.0.0  no
839       matter what version your dependencies rely on:
840
841         {
842           "overrides": {
843             "foo": "1.0.0"
844           }
845         }
846
847       The above is a short hand notation, the full object form can be used to
848       allow overriding a package itself as well as a child  of  the  package.
849       This  will  cause  foo  to always be 1.0.0 while also making bar at any
850       depth beyond foo also 1.0.0:
851
852         {
853           "overrides": {
854             "foo": {
855               ".": "1.0.0",
856               "bar": "1.0.0"
857             }
858           }
859         }
860
861       To only override foo to be 1.0.0 when it's a child (or  grandchild,  or
862       great grandchild, etc) of the package bar:
863
864         {
865           "overrides": {
866             "bar": {
867               "foo": "1.0.0"
868             }
869           }
870         }
871
872       Keys  can  be nested to any arbitrary length. To override foo only when
873       it's a child of bar and only when bar is a child of baz:
874
875         {
876           "overrides": {
877             "baz": {
878               "bar": {
879                 "foo": "1.0.0"
880               }
881             }
882           }
883         }
884
885       The key of an override can also include a version,  or  range  of  ver‐
886       sions.   To  override  foo  to  1.0.0,  but  only  when it's a child of
887       bar@2.0.0:
888
889         {
890           "overrides": {
891             "bar@2.0.0": {
892               "foo": "1.0.0"
893             }
894           }
895         }
896
897       You may not set an override for a package that you directly  depend  on
898       unless both the dependency and the override itself share the exact same
899       spec. To make this limitation easier to deal with, overrides  may  also
900       be  defined as a reference to a spec for a direct dependency by prefix‐
901       ing the name of the package you wish the version to match with a $.
902
903         {
904           "dependencies": {
905             "foo": "^1.0.0"
906           },
907           "overrides": {
908             // BAD, will throw an EOVERRIDE error
909             // "foo": "^2.0.0"
910             // GOOD, specs match so override is allowed
911             // "foo": "^1.0.0"
912             // BEST, the override is defined as a reference to the dependency
913             "foo": "$foo",
914             // the referenced package does not need to match the overridden one
915             "bar": "$foo"
916           }
917         }
918
919   engines
920       You can specify the version of node that your stuff works on:
921
922         {
923           "engines": {
924             "node": ">=0.10.3 <15"
925           }
926         }
927
928       And, like with dependencies, if you don't specify the  version  (or  if
929       you specify "*" as the version), then any version of node will do.
930
931       You  can  also use the "engines" field to specify which versions of npm
932       are capable of properly installing your program.  For example:
933
934         {
935           "engines": {
936             "npm": "~1.0.20"
937           }
938         }
939
940       Unless the user has set the engine-strict config flag,  this  field  is
941       advisory  only  and will only produce warnings when your package is in‐
942       stalled as a dependency.
943
944   os
945       You can specify which operating systems your module will run on:
946
947         {
948           "os": [
949             "darwin",
950             "linux"
951           ]
952         }
953
954       You can also block instead of allowing operating systems, just  prepend
955       the blocked os with a '!':
956
957         {
958           "os": [
959             "!win32"
960           ]
961         }
962
963       The host operating system is determined by process.platform
964
965       It is allowed to both block and allow an item, although there isn't any
966       good reason to do this.
967
968   cpu
969       If your code only runs on certain cpu architectures,  you  can  specify
970       which ones.
971
972         {
973           "cpu": [
974             "x64",
975             "ia32"
976           ]
977         }
978
979       Like the os option, you can also block architectures:
980
981         {
982           "cpu": [
983             "!arm",
984             "!mips"
985           ]
986         }
987
988       The host architecture is determined by process.arch
989
990   private
991       If  you  set "private": true in your package.json, then npm will refuse
992       to publish it.
993
994       This is a way to prevent accidental publication  of  private  reposito‐
995       ries.   If  you  would like to ensure that a given package is only ever
996       published to a specific registry (for example, an  internal  registry),
997       then  use  the publishConfig dictionary described below to override the
998       registry config param at publish-time.
999
1000   publishConfig
1001       This is a set of config values that will be used at publish-time.  It's
1002       especially  handy  if  you  want to set the tag, registry or access, so
1003       that you can ensure that a given package is not tagged  with  "latest",
1004       published to the global public registry or that a scoped module is pri‐
1005       vate by default.
1006
1007       See npm help config to see the list of config options that can be over‐
1008       ridden.
1009
1010   workspaces
1011       The  optional  workspaces  field  is an array of file patterns that de‐
1012       scribes locations within the local file system that the install  client
1013       should  look  up  to find each npm help workspace that needs to be sym‐
1014       linked to the top level node_modules folder.
1015
1016       It can describe either the direct paths of the folders to  be  used  as
1017       workspaces or it can define globs that will resolve to these same fold‐
1018       ers.
1019
1020       In the following example, all folders located inside the folder ./pack‐
1021       ages  will  be  treated  as workspaces as long as they have valid pack‐
1022       age.json files inside them:
1023
1024         {
1025           "name": "workspace-example",
1026           "workspaces": [
1027             "./packages/*"
1028           ]
1029         }
1030
1031       See npm help workspaces for more examples.
1032
1033   DEFAULT VALUES
1034       npm will default some values based on package contents.
1035
1036"scripts": {"start": "node server.js"} If there is a  server.js  file
1037         in  the root of your package, then npm will default the start command
1038         to node server.js.
1039
1040"scripts":{"install": "node-gyp rebuild"} If there is  a  binding.gyp
1041         file  in the root of your package and you have not defined an install
1042         or preinstall script, npm will default the install command to compile
1043         using node-gyp.
1044
1045"contributors":  [...]   If  there  is an AUTHORS file in the root of
1046         your package, npm will treat each line as a Name <email>  (url)  for‐
1047         mat, where email and url are optional.  Lines which start with a # or
1048         are blank, will be ignored.
1049
1050
1051   SEE ALSO
1052       • semver https://github.com/npm/node-semver#versions
1053
1054       • npm help workspaces
1055
1056       • npm help init
1057
1058       • npm help version
1059
1060       • npm help config
1061
1062       • npm help help
1063
1064       • npm help install
1065
1066       • npm help publish
1067
1068       • npm help uninstall
1069
1070
1071
1072
1073                                 January 2022                  PACKAGE.JSON(5)
Impressum