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
124 https://www.npmjs.com/package/spdx, 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 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 {
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 packages root folder.
326 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 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 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 For example, myapp could have this:
347 {
349 "bin": {
350 "myapp": "./cli.js"
351 }
352 }
353 So, when you install myapp, it'll create a symlink from the cli.js
355 script to /usr/local/bin/myapp.
356 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 {
361 "name": "my-program",
362 "version": "1.2.5",
363 "bin": "./path/to/program"
364 }
365 would be the same as this:
367 {
369 "name": "my-program",
370 "version": "1.2.5",
371 "bin": {
372 "my-program": "./path/to/program"
373 }
374 }
375 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 Note that you can also set the executable files using directories.bin
381 #directoriesbin.
382 See npm help folders for more info on executables.
384 man
386 Specify either a single file or an array of filenames to put in place
387 for the man program to find.
388 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 {
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 would link the ./man/doc.1 file in such that it is the target for man
402 foo
403 If the filename doesn't start with the package name, then it's pre‐
405 fixed. So, this:
406 {
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 will create files to do man foo and man foo-bar.
419 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 {
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 will create entries for man foo and man 2 foo
436 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 In the future, this information may be used in other creative ways.
445 directories.bin
447 If you specify a bin directory in directories.bin, all the files in
448 that folder will be added.
449 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 directories.man
456 A folder that is full of man pages. Sugar to generate a "man" array by
457 walking the folder.
458 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 Do it like this:
465 {
467 "repository": {
468 "type": "git",
469 "url": "https://github.com/npm/cli.git"
470 }
471 }
472 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 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use
479 the same shortcut syntax you use for npm install:
480 {
482 "repository": "npm/npm",
483 "repository": "github:user/repo",
485 "repository": "gist:11081aaa281",
487 "repository": "bitbucket:user/repo",
489 "repository": "gitlab:user/repo"
491 }
492 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 {
498 "repository": {
499 "type": "git",
500 "url": "https://github.com/facebook/react.git",
501 "directory": "packages/react-dom"
502 }
503 }
504 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 See npm help scripts to find out more about writing package scripts.
511 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 {
518 "name": "foo",
519 "config": {
520 "port": "8080"
521 }
522 }
523 It could also have a "start" command that referenced the npm_pack‐
525 age_config_port environment variable.
526 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 Please do not put test harnesses or transpilers or other "development"
534 time tools in your dependencies object. See devDependencies, below.
535 See semver https://github.com/npm/node-semver#versions for more details
537 about specifying version ranges.
538 • version Must match version exactly
540 • >version Must be greater than version
542 • >=version etc
544 • <version
546 • <=version
548 • ~version "Approximately equivalent to version" See semver
550 https://github.com/npm/node-semver#versions
551 • ^version "Compatible with version" See semver
553 https://github.com/npm/node-semver#versions
554 • 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
556 • http://... See 'URLs as Dependencies' below
558 • * Matches any version
560 • "" (just an empty string) Same as *
562 • version1 - version2 Same as >=version1 <=version2.
564 • range1 || range2 Passes if either range1 or range2 are satisfied.
566 • git... See 'Git URLs as Dependencies' below
568 • user/repo See 'GitHub URLs' below
570 • tag A specific version tagged and published as tag See npm help npm
572 dist-tag
573 • path/path/path See Local Paths #local-paths below
575 For example, these are all valid:
578 {
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 URLs as Dependencies
597 You may specify a tarball URL in place of a version range.
598 This tarball will be downloaded and installed locally to your package
600 at install time.
601 Git URLs as Dependencies
603 Git urls are of the form:
604 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
606 <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
608 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 Examples:
617 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 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 {
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 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 ../foo/bar
644 ~/foo/bar
645 ./foo/bar
646 /foo/bar
647 in which case they will be normalized to a relative path and added to
649 your package.json. For example:
650 {
652 "name": "baz",
653 "dependencies": {
654 "bar": "file:../foo/bar"
655 }
656 }
657 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 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 In this case, it's best to map these additional items in a devDependen‐
669 cies object.
670 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 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 For example:
680 {
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 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 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 For example:
707 {
709 "name": "tea-latte",
710 "version": "1.3.5",
711 "peerDependencies": {
712 "tea": "2.x"
713 }
714 }
715 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 ├── tea-latte@1.3.5
721 └── tea@2.2.0
722 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 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 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 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 For example:
747 {
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 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 bundledDependencies
768 This defines an array of package names that will be bundled when pub‐
769 lishing the package.
770 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 For example:
777 If we define a package.json like this:
779 {
781 "name": "awesome-web-framework",
782 "version": "1.0.0",
783 "bundledDependencies": [
784 "renderized",
785 "super-streams"
786 ]
787 }
788 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 If this is spelled "bundleDependencies", then that is also honored.
796 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 It is still your program's responsibility to handle the lack of the de‐
806 pendency. For example, something like this:
807 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 // .. then later in your program ..
819 if (foo) {
821 foo.doFooThings()
822 }
823 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 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 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 To make sure the package foo is always installed as version 1.0.0 no
839 matter what version your dependencies rely on:
840 {
842 "overrides": {
843 "foo": "1.0.0"
844 }
845 }
846 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 {
853 "overrides": {
854 "foo": {
855 ".": "1.0.0",
856 "bar": "1.0.0"
857 }
858 }
859 }
860 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 {
865 "overrides": {
866 "bar": {
867 "foo": "1.0.0"
868 }
869 }
870 }
871 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 {
876 "overrides": {
877 "baz": {
878 "bar": {
879 "foo": "1.0.0"
880 }
881 }
882 }
883 }
884 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 {
890 "overrides": {
891 "bar@2.0.0": {
892 "foo": "1.0.0"
893 }
894 }
895 }
896 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 {
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 engines
920 You can specify the version of node that your stuff works on:
921 {
923 "engines": {
924 "node": ">=0.10.3 <15"
925 }
926 }
927 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 You can also use the "engines" field to specify which versions of npm
932 are capable of properly installing your program. For example:
933 {
935 "engines": {
936 "npm": "~1.0.20"
937 }
938 }
939 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 os
945 You can specify which operating systems your module will run on:
946 {
948 "os": [
949 "darwin",
950 "linux"
951 ]
952 }
953 You can also block instead of allowing operating systems, just prepend
955 the blocked os with a '!':
956 {
958 "os": [
959 "!win32"
960 ]
961 }
962 The host operating system is determined by process.platform
964 It is allowed to both block and allow an item, although there isn't any
966 good reason to do this.
967 cpu
969 If your code only runs on certain cpu architectures, you can specify
970 which ones.
971 {
973 "cpu": [
974 "x64",
975 "ia32"
976 ]
977 }
978 Like the os option, you can also block architectures:
980 {
982 "cpu": [
983 "!arm",
984 "!mips"
985 ]
986 }
987 The host architecture is determined by process.arch
989 private
991 If you set "private": true in your package.json, then npm will refuse
992 to publish it.
993 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 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 See npm help config to see the list of config options that can be over‐
1008 ridden.
1009 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 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 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 {
1025 "name": "workspace-example",
1026 "workspaces": [
1027 "./packages/*"
1028 ]
1029 }
1030 See npm help workspaces for more examples.
1032 DEFAULT VALUES
1034 npm will default some values based on package contents.
1035 • "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 • "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 • "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 SEE ALSO
1052 • semver https://github.com/npm/node-semver#versions
1053 • npm help workspaces
1055 • npm help init
1057 • npm help version
1059 • npm help config
1061 • npm help help
1063 • npm help install
1065 • npm help publish
1067 • npm help uninstall
1069 January 2022 PACKAGE.JSON(5)