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 object
11 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 in‐
29 cludes 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 non-
38 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
47 engine 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
53 by 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 ⟨https://github.com/npm/node-
69 semver⟩, which is bundled with npm as a dependency. (npm install semver
70 to use it yourself.)
71 description
73 Put a description in it. It's a string. This helps people discover your
74 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 "bugs": {
96 "url": "https://github.com/owner/project/issues",
97 "email": "project@hostname.com"
98 }
99 }
100 You can specify either one or both values. If you want to provide only
102 a url, you can specify the value for "bugs" as a simple string instead
103 of an object.
104 If a url is provided, it will be used by the npm bugs command.
106 license
108 You should specify a license for your package so that people know how
109 they are permitted to use it, and any restrictions you're placing on
110 it.
111 If you're using a common license such as BSD-2-Clause or MIT, add a
113 current SPDX license identifier for the license you're using, like
114 this:
115 {
117 "license" : "BSD-3-Clause"
118 }
119 You can check the full list of SPDX license IDs ⟨https://spdx.org/li‐
121 censes/⟩. Ideally you should pick one that is OSI ⟨https://open‐
122 source.org/licenses/⟩ approved.
123 If your package is licensed under multiple common licenses, use an SPDX
125 license expression syntax version 2.0 string ⟨https://spdx.dev/specifi‐
126 cations/⟩, like this:
127 {
129 "license" : "(ISC OR GPL-3.0)"
130 }
131 If you are using a license that hasn't been assigned an SPDX identi‐
133 fier, or if you are using a custom license, use a string value like
134 this one:
135 {
137 "license" : "SEE LICENSE IN <filename>"
138 }
139 Then include a file named <filename> at the top level of the package.
141 Some old packages used license objects or a "licenses" property con‐
143 taining an array of license objects:
144 // Not valid metadata
146 {
147 "license" : {
148 "type" : "ISC",
149 "url" : "https://opensource.org/licenses/ISC"
150 }
151 }
152 // Not valid metadata
154 {
155 "licenses" : [
156 {
157 "type": "MIT",
158 "url": "https://www.opensource.org/licenses/mit-license.php"
159 },
160 {
161 "type": "Apache-2.0",
162 "url": "https://opensource.org/licenses/apache2.0.php"
163 }
164 ]
165 }
166 Those styles are now deprecated. Instead, use SPDX expressions, like
168 this:
169 {
171 "license": "ISC"
172 }
173 {
175 "license": "(MIT OR Apache-2.0)"
176 }
177 Finally, if you do not wish to grant others the right to use a private
179 or unpublished package under any terms:
180 {
182 "license": "UNLICENSED"
183 }
184 Consider also setting "private": true to prevent accidental publica‐
186 tion.
187 people fields: author, contributors
189 The "author" is one person. "contributors" is an array of people. A
190 "person" is an object with a "name" field and optionally "url" and
191 "email", like this:
192 {
194 "name" : "Barney Rubble",
195 "email" : "b@rubble.com",
196 "url" : "http://barnyrubble.tumblr.com/"
197 }
198 Or you can shorten that all into a single string, and npm will parse it
200 for you:
201 {
203 "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"
204 }
205 Both email and url are optional either way.
207 npm also sets a top-level "maintainers" field with your npm user info.
209 funding
211 You can specify an object containing a URL that provides up-to-date in‐
212 formation about ways to help fund development of your package, or a
213 string URL, or an array of these:
214 {
216 "funding": {
217 "type" : "individual",
218 "url" : "http://example.com/donate"
219 },
220 "funding": {
222 "type" : "patreon",
223 "url" : "https://www.patreon.com/my-account"
224 },
225 "funding": "http://example.com/donate",
227 "funding": [
229 {
230 "type" : "individual",
231 "url" : "http://example.com/donate"
232 },
233 "http://example.com/donateAlso",
234 {
235 "type" : "patreon",
236 "url" : "https://www.patreon.com/my-account"
237 }
238 ]
239 }
240 Users can use the npm fund subcommand to list the funding URLs of all
242 dependencies of their project, direct and indirect. A shortcut to visit
243 each funding url is also available when providing the project name such
244 as: npm fund <projectname> (when there are multiple URLs, the first one
245 will be visited)
246 files
248 The optional files field is an array of file patterns that describes
249 the entries to be included when your package is installed as a depen‐
250 dency. File patterns follow a similar syntax to .gitignore, but re‐
251 versed: including a file, directory, or glob pattern (*, **/*, and
252 such) will make it so that file is included in the tarball when it's
253 packed. Omitting the field will make it default to ["*"], which means
254 it will include all files.
255 Some special files and directories are also included or excluded re‐
257 gardless of whether they exist in the files array (see below).
258 You can also provide a .npmignore file in the root of your package or
260 in subdirectories, which will keep files from being included. At the
261 root of your package it will not override the "files" field, but in
262 subdirectories it will. The .npmignore file works just like a .gitig‐
263 nore. If there is a .gitignore file, and .npmignore is missing, .gitig‐
264 nore's contents will be used instead.
265 Certain files are always included, regardless of settings:
267 • package.json
269 • README
271 • LICENSE / LICENCE
273 • The file in the "main" field
275 • The file(s) in the "bin" field
277 README & LICENSE can have any case and extension.
280 Conversely, some files are always ignored:
282 • .git
284 • CVS
286 • .svn
288 • .hg
290 • .lock-wscript
292 • .wafpickle-N
294 • .*.swp
296 • .DS_Store
298 • ._*
300 • npm-debug.log
302 • .npmrc
304 • node_modules
306 • config.gypi
308 • *.orig
310 • package-lock.json (use npm-shrinkwrap.json ⟨/configuring-npm/npm-
312 shrinkwrap-json⟩ if you wish it to be published)
313 main
316 The main field is a module ID that is the primary entry point to your
317 program. That is, if your package is named foo, and a user installs it,
318 and then does require("foo"), then your main module's exports object
319 will be returned.
320 This should be a module relative to the root of your package folder.
322 For most modules, it makes the most sense to have a main script and of‐
324 ten not much else.
325 If main is not set, it defaults to index.js in the package's root
327 folder.
328 browser
330 If your module is meant to be used client-side the browser field should
331 be used instead of the main field. This is helpful to hint users that
332 it might rely on primitives that aren't available in Node.js modules.
333 (e.g. window)
334 bin
336 A lot of packages have one or more executable files that they'd like to
337 install into the PATH. npm makes this pretty easy (in fact, it uses
338 this feature to install the "npm" executable.)
339 To use this, supply a bin field in your package.json which is a map of
341 command name to local file name. When this package is installed glob‐
342 ally, that file will be either linked inside the global bins directory
343 or a cmd (Windows Command File) will be created which executes the
344 specified file in the bin field, so it is available to run by name or
345 name.cmd (on Windows PowerShell). When this package is installed as a
346 dependency in another package, the file will be linked where it will be
347 available to that package either directly by npm exec or by name in
348 other scripts when invoking them via npm run-script.
349 For example, myapp could have this:
351 {
353 "bin": {
354 "myapp": "./cli.js"
355 }
356 }
357 So, when you install myapp, in case of unix-like OS it'll create a sym‐
359 link from the cli.js script to /usr/local/bin/myapp and in case of win‐
360 dows it will create a cmd file usually at C:\Users\{Username}\App‐
361 Data\Roaming\npm\myapp.cmd which runs the cli.js script.
362 If you have a single executable, and its name should be the name of the
364 package, then you can just supply it as a string. For example:
365 {
367 "name": "my-program",
368 "version": "1.2.5",
369 "bin": "./path/to/program"
370 }
371 would be the same as this:
373 {
375 "name": "my-program",
376 "version": "1.2.5",
377 "bin": {
378 "my-program": "./path/to/program"
379 }
380 }
381 Please make sure that your file(s) referenced in bin starts with
383 #!/usr/bin/env node, otherwise the scripts are started without the node
384 executable!
385 Note that you can also set the executable files using directories.bin
387 (directories.bin).
388 See folders ⟨/configuring-npm/folders#executables⟩ for more info on ex‐
390 ecutables.
391 man
393 Specify either a single file or an array of filenames to put in place
394 for the man program to find.
395 If only a single file is provided, then it's installed such that it is
397 the result from man <pkgname>, regardless of its actual filename. For
398 example:
399 {
401 "name": "foo",
402 "version": "1.2.3",
403 "description": "A packaged foo fooer for fooing foos",
404 "main": "foo.js",
405 "man": "./man/doc.1"
406 }
407 would link the ./man/doc.1 file in such that it is the target for man
409 foo
410 If the filename doesn't start with the package name, then it's pre‐
412 fixed. So, this:
413 {
415 "name": "foo",
416 "version": "1.2.3",
417 "description": "A packaged foo fooer for fooing foos",
418 "main": "foo.js",
419 "man": [
420 "./man/foo.1",
421 "./man/bar.1"
422 ]
423 }
424 will create files to do man foo and man foo-bar.
426 Man files must end with a number, and optionally a .gz suffix if they
428 are compressed. The number dictates which man section the file is in‐
429 stalled into.
430 {
432 "name": "foo",
433 "version": "1.2.3",
434 "description": "A packaged foo fooer for fooing foos",
435 "main": "foo.js",
436 "man": [
437 "./man/foo.1",
438 "./man/foo.2"
439 ]
440 }
441 will create entries for man foo and man 2 foo
443 directories
445 The CommonJS Packages ⟨http://wiki.commonjs.org/wiki/Packages/1.0⟩ spec
446 details a few ways that you can indicate the structure of your package
447 using a directories object. If you look at npm's package.json
448 ⟨https://registry.npmjs.org/npm/latest⟩, you'll see that it has direc‐
449 tories for doc, lib, and man.
450 In the future, this information may be used in other creative ways.
452 directories.bin
454 If you specify a bin directory in directories.bin, all the files in
455 that folder will be added.
456 Because of the way the bin directive works, specifying both a bin path
458 and setting directories.bin is an error. If you want to specify indi‐
459 vidual files, use bin, and for all the files in an existing bin direc‐
460 tory, use directories.bin.
461 directories.man
463 A folder that is full of man pages. Sugar to generate a "man" array by
464 walking the folder.
465 repository
467 Specify the place where your code lives. This is helpful for people who
468 want to contribute. If the git repo is on GitHub, then the npm docs
469 command will be able to find you.
470 Do it like this:
472 {
474 "repository": {
475 "type": "git",
476 "url": "https://github.com/npm/cli.git"
477 }
478 }
479 The URL should be a publicly available (perhaps read-only) url that can
481 be handed directly to a VCS program without any modification. It should
482 not be a url to an html project page that you put in your browser. It's
483 for computers.
484 For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use
486 the same shortcut syntax you use for npm install:
487 {
489 "repository": "npm/npm",
490 "repository": "github:user/repo",
492 "repository": "gist:11081aaa281",
494 "repository": "bitbucket:user/repo",
496 "repository": "gitlab:user/repo"
498 }
499 If the package.json for your package is not in the root directory (for
501 example if it is part of a monorepo), you can specify the directory in
502 which it lives:
503 {
505 "repository": {
506 "type": "git",
507 "url": "https://github.com/facebook/react.git",
508 "directory": "packages/react-dom"
509 }
510 }
511 scripts
513 The "scripts" property is a dictionary containing script commands that
514 are run at various times in the lifecycle of your package. The key is
515 the lifecycle event, and the value is the command to run at that point.
516 See npm help scripts to find out more about writing package scripts.
518 config
520 A "config" object can be used to set configuration parameters used in
521 package scripts that persist across upgrades. For instance, if a pack‐
522 age had the following:
523 {
525 "name": "foo",
526 "config": {
527 "port": "8080"
528 }
529 }
530 It could also have a "start" command that referenced the npm_pack‐
532 age_config_port environment variable.
533 dependencies
535 Dependencies are specified in a simple object that maps a package name
536 to a version range. The version range is a string which has one or more
537 space-separated descriptors. Dependencies can also be identified with a
538 tarball or git URL.
539 Please do not put test harnesses or transpilers or other "development"
541 time tools in your dependencies object. See devDependencies, below.
542 See semver ⟨https://github.com/npm/node-semver#versions⟩ for more de‐
544 tails about specifying version ranges.
545 • version Must match version exactly
547 • >version Must be greater than version
549 • >=version etc
551 • <version
553 • <=version
555 • ~version "Approximately equivalent to version" See semver
557 ⟨https://github.com/npm/node-semver#versions⟩
558 • ^version "Compatible with version" See semver
560 ⟨https://github.com/npm/node-semver#versions⟩
561 • 1.2.x 1.2.0, 1.2.1, etc., but not 1.3.0
563 • http://... See 'URLs as Dependencies' below
565 • * Matches any version
567 • "" (just an empty string) Same as *
569 • version1 - version2 Same as >=version1 <=version2.
571 • range1 || range2 Passes if either range1 or range2 are satisfied.
573 • git... See 'Git URLs as Dependencies' below
575 • user/repo See 'GitHub URLs' below
577 • tag A specific version tagged and published as tag See npm help
579 dist-tag
580 • path/path/path See Local Paths (Local Paths) below
582 For example, these are all valid:
585 {
587 "dependencies": {
588 "foo": "1.0.0 - 2.9999.9999",
589 "bar": ">=1.0.2 <2.1.2",
590 "baz": ">1.0.2 <=2.3.4",
591 "boo": "2.0.1",
592 "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
593 "asd": "http://asdf.com/asdf.tar.gz",
594 "til": "~1.2",
595 "elf": "~1.2.3",
596 "two": "2.x",
597 "thr": "3.3.x",
598 "lat": "latest",
599 "dyl": "file:../dyl"
600 }
601 }
602 URLs as Dependencies
604 You may specify a tarball URL in place of a version range.
605 This tarball will be downloaded and installed locally to your package
607 at install time.
608 Git URLs as Dependencies
610 Git urls are of the form:
611 <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
613 <protocol> is one of git, git+ssh, git+http, git+https, or git+file.
615 If #<commit-ish> is provided, it will be used to clone exactly that
617 commit. If the commit-ish has the format #semver:<semver>, <semver> can
618 be any valid semver range or exact version, and npm will look for any
619 tags or refs matching that range in the remote repository, much as it
620 would for a registry dependency. If neither #<commit-ish> or
621 #semver:<semver> is specified, then the default branch is used.
622 Examples:
624 git+ssh://git@github.com:npm/cli.git#v1.0.27
626 git+ssh://git@github.com:npm/cli#semver:^5.0
627 git+https://isaacs@github.com/npm/cli.git
628 git://github.com/npm/cli.git#v1.0.27
629 When installing from a git repository, the presence of certain fields
631 in the package.json will cause npm to believe it needs to perform a
632 build. To do so your repository will be cloned into a temporary direc‐
633 tory, all of its deps installed, relevant scripts run, and the result‐
634 ing directory packed and installed.
635 This flow will occur if your git dependency uses workspaces, or if any
637 of the following scripts are present:
638 • build
640 • prepare
642 • prepack
644 • preinstall
646 • install
648 • postinstall
650 If your git repository includes pre-built artifacts, you will likely
653 want to make sure that none of the above scripts are defined, or your
654 dependency will be rebuilt for every installation.
655 GitHub URLs
657 As of version 1.1.65, you can refer to GitHub urls as just "foo":
658 "user/foo-project". Just as with git URLs, a commit-ish suffix can be
659 included. For example:
660 {
662 "name": "foo",
663 "version": "0.0.0",
664 "dependencies": {
665 "express": "expressjs/express",
666 "mocha": "mochajs/mocha#4727d357ea",
667 "module": "user/repo#feature\/branch"
668 }
669 }
670 Local Paths
672 As of version 2.0.0 you can provide a path to a local directory that
673 contains a package. Local paths can be saved using npm install -S or
674 npm install --save, using any of these forms:
675 ~/foo/bar
677 /foo/bar
678 in which case they will be normalized to a relative path and added to
680 your package.json. For example:
681 {
683 "name": "baz",
684 "dependencies": {
685 "bar": "file:../foo/bar"
686 }
687 }
688 This feature is helpful for local offline development and creating
690 tests that require npm installing where you don't want to hit an exter‐
691 nal server, but should not be used when publishing packages to the pub‐
692 lic registry.
693 note: Packages linked by local path will not have their own dependen‐
695 cies installed when npm install is ran in this case. You must run npm
696 install from inside the local path itself.
697 devDependencies
699 If someone is planning on downloading and using your module in their
700 program, then they probably don't want or need to download and build
701 the external test or documentation framework that you use.
702 In this case, it's best to map these additional items in a devDependen‐
704 cies object.
705 These things will be installed when doing npm link or npm install from
707 the root of a package, and can be managed like any other npm configura‐
708 tion param. See npm help config for more on the topic.
709 For build steps that are not platform-specific, such as compiling Cof‐
711 feeScript or other languages to JavaScript, use the prepare script to
712 do this, and make the required package a devDependency.
713 For example:
715 {
717 "name": "ethopia-waza",
718 "description": "a delightfully fruity coffee varietal",
719 "version": "1.2.3",
720 "devDependencies": {
721 "coffee-script": "~1.6.3"
722 },
723 "scripts": {
724 "prepare": "coffee -o lib/ -c src/waza.coffee"
725 },
726 "main": "lib/waza.js"
727 }
728 The prepare script will be run before publishing, so that users can
730 consume the functionality without requiring them to compile it them‐
731 selves. In dev mode (ie, locally running npm install), it'll run this
732 script as well, so that you can test it easily.
733 peerDependencies
735 In some cases, you want to express the compatibility of your package
736 with a host tool or library, while not necessarily doing a require of
737 this host. This is usually referred to as a plugin. Notably, your mod‐
738 ule may be exposing a specific interface, expected and specified by the
739 host documentation.
740 For example:
742 {
744 "name": "tea-latte",
745 "version": "1.3.5",
746 "peerDependencies": {
747 "tea": "2.x"
748 }
749 }
750 This ensures your package tea-latte can be installed along with the
752 second major version of the host package tea only. npm install tea-
753 latte could possibly yield the following dependency graph:
754 ├── tea-latte@1.3.5
756 └── tea@2.2.0
757 In npm versions 3 through 6, peerDependencies were not automatically
759 installed, and would raise a warning if an invalid version of the peer
760 dependency was found in the tree. As of npm v7, peerDependencies are
761 installed by default.
762 Trying to install another plugin with a conflicting requirement may
764 cause an error if the tree cannot be resolved correctly. For this rea‐
765 son, make sure your plugin requirement is as broad as possible, and not
766 to lock it down to specific patch versions.
767 Assuming the host complies with semver ⟨https://semver.org/⟩, only
769 changes in the host package's major version will break your plugin.
770 Thus, if you've worked with every 1.x version of the host package, use
771 "^1.0" or "1.x" to express this. If you depend on features introduced
772 in 1.5.2, use "^1.5.2".
773 peerDependenciesMeta
775 When a user installs your package, npm will emit warnings if packages
776 specified in peerDependencies are not already installed. The peerDepen‐
777 denciesMeta field serves to provide npm more information on how your
778 peer dependencies are to be used. Specifically, it allows peer depen‐
779 dencies to be marked as optional.
780 For example:
782 {
784 "name": "tea-latte",
785 "version": "1.3.5",
786 "peerDependencies": {
787 "tea": "2.x",
788 "soy-milk": "1.2"
789 },
790 "peerDependenciesMeta": {
791 "soy-milk": {
792 "optional": true
793 }
794 }
795 }
796 Marking a peer dependency as optional ensures npm will not emit a warn‐
798 ing if the soy-milk package is not installed on the host. This allows
799 you to integrate and interact with a variety of host packages without
800 requiring all of them to be installed.
801 bundleDependencies
803 This defines an array of package names that will be bundled when pub‐
804 lishing the package.
805 In cases where you need to preserve npm packages locally or have them
807 available through a single file download, you can bundle the packages
808 in a tarball file by specifying the package names in the bundleDepen‐
809 dencies array and executing npm pack.
810 For example:
812 If we define a package.json like this:
814 {
816 "name": "awesome-web-framework",
817 "version": "1.0.0",
818 "bundleDependencies": [
819 "renderized",
820 "super-streams"
821 ]
822 }
823 we can obtain awesome-web-framework-1.0.0.tgz file by running npm pack.
825 This file contains the dependencies renderized and super-streams which
826 can be installed in a new project by executing npm install awesome-web-
827 framework-1.0.0.tgz. Note that the package names do not include any
828 versions, as that information is specified in dependencies.
829 If this is spelled "bundledDependencies", then that is also honored.
831 Alternatively, "bundleDependencies" can be defined as a boolean value.
833 A value of true will bundle all dependencies, a value of false will
834 bundle none.
835 optionalDependencies
837 If a dependency can be used, but you would like npm to proceed if it
838 cannot be found or fails to install, then you may put it in the option‐
839 alDependencies object. This is a map of package name to version or url,
840 just like the dependencies object. The difference is that build fail‐
841 ures do not cause installation to fail. Running npm install --omit=op‐
842 tional will prevent these dependencies from being installed.
843 It is still your program's responsibility to handle the lack of the de‐
845 pendency. For example, something like this:
846 try {
848 var foo = require('foo')
849 var fooVersion = require('foo/package.json').version
850 } catch (er) {
851 foo = null
852 }
853 if ( notGoodFooVersion(fooVersion) ) {
854 foo = null
855 }
856 // .. then later in your program ..
858 if (foo) {
860 foo.doFooThings()
861 }
862 Entries in optionalDependencies will override entries of the same name
864 in dependencies, so it's usually best to only put in one place.
865 overrides
867 If you need to make specific changes to dependencies of your dependen‐
868 cies, for example replacing the version of a dependency with a known
869 security issue, replacing an existing dependency with a fork, or making
870 sure that the same version of a package is used everywhere, then you
871 may add an override.
872 Overrides provide a way to replace a package in your dependency tree
874 with another version, or another package entirely. These changes can be
875 scoped as specific or as vague as desired.
876 To make sure the package foo is always installed as version 1.0.0 no
878 matter what version your dependencies rely on:
879 {
881 "overrides": {
882 "foo": "1.0.0"
883 }
884 }
885 The above is a short hand notation, the full object form can be used to
887 allow overriding a package itself as well as a child of the package.
888 This will cause foo to always be 1.0.0 while also making bar at any
889 depth beyond foo also 1.0.0:
890 {
892 "overrides": {
893 "foo": {
894 ".": "1.0.0",
895 "bar": "1.0.0"
896 }
897 }
898 }
899 To only override foo to be 1.0.0 when it's a child (or grandchild, or
901 great grandchild, etc) of the package bar:
902 {
904 "overrides": {
905 "bar": {
906 "foo": "1.0.0"
907 }
908 }
909 }
910 Keys can be nested to any arbitrary length. To override foo only when
912 it's a child of bar and only when bar is a child of baz:
913 {
915 "overrides": {
916 "baz": {
917 "bar": {
918 "foo": "1.0.0"
919 }
920 }
921 }
922 }
923 The key of an override can also include a version, or range of ver‐
925 sions. To override foo to 1.0.0, but only when it's a child of
926 bar@2.0.0:
927 {
929 "overrides": {
930 "bar@2.0.0": {
931 "foo": "1.0.0"
932 }
933 }
934 }
935 You may not set an override for a package that you directly depend on
937 unless both the dependency and the override itself share the exact same
938 spec. To make this limitation easier to deal with, overrides may also
939 be defined as a reference to a spec for a direct dependency by prefix‐
940 ing the name of the package you wish the version to match with a $.
941 {
943 "dependencies": {
944 "foo": "^1.0.0"
945 },
946 "overrides": {
947 // BAD, will throw an EOVERRIDE error
948 // "foo": "^2.0.0"
949 // GOOD, specs match so override is allowed
950 // "foo": "^1.0.0"
951 // BEST, the override is defined as a reference to the dependency
952 "foo": "$foo",
953 // the referenced package does not need to match the overridden one
954 "bar": "$foo"
955 }
956 }
957 engines
959 You can specify the version of node that your stuff works on:
960 {
962 "engines": {
963 "node": ">=0.10.3 <15"
964 }
965 }
966 And, like with dependencies, if you don't specify the version (or if
968 you specify "*" as the version), then any version of node will do.
969 You can also use the "engines" field to specify which versions of npm
971 are capable of properly installing your program. For example:
972 {
974 "engines": {
975 "npm": "~1.0.20"
976 }
977 }
978 Unless the user has set the engine-strict config ⟨/using-npm/config#en‐
980 gine-strict⟩ flag, this field is advisory only and will only produce
981 warnings when your package is installed as a dependency.
982 os
984 You can specify which operating systems your module will run on:
985 {
987 "os": [
988 "darwin",
989 "linux"
990 ]
991 }
992 You can also block instead of allowing operating systems, just prepend
994 the blocked os with a '!':
995 {
997 "os": [
998 "!win32"
999 ]
1000 }
1001 The host operating system is determined by process.platform
1003 It is allowed to both block and allow an item, although there isn't any
1005 good reason to do this.
1006 cpu
1008 If your code only runs on certain cpu architectures, you can specify
1009 which ones.
1010 {
1012 "cpu": [
1013 "x64",
1014 "ia32"
1015 ]
1016 }
1017 Like the os option, you can also block architectures:
1019 {
1021 "cpu": [
1022 "!arm",
1023 "!mips"
1024 ]
1025 }
1026 The host architecture is determined by process.arch
1028 private
1030 If you set "private": true in your package.json, then npm will refuse
1031 to publish it.
1032 This is a way to prevent accidental publication of private reposito‐
1034 ries. If you would like to ensure that a given package is only ever
1035 published to a specific registry (for example, an internal registry),
1036 then use the publishConfig dictionary described below to override the
1037 registry config param at publish-time.
1038 publishConfig
1040 This is a set of config values that will be used at publish-time. It's
1041 especially handy if you want to set the tag, registry or access, so
1042 that you can ensure that a given package is not tagged with "latest",
1043 published to the global public registry or that a scoped module is pri‐
1044 vate by default.
1045 See npm help config to see the list of config options that can be over‐
1047 ridden.
1048 workspaces
1050 The optional workspaces field is an array of file patterns that de‐
1051 scribes locations within the local file system that the install client
1052 should look up to find each npm help workspace that needs to be sym‐
1053 linked to the top level node_modules folder.
1054 It can describe either the direct paths of the folders to be used as
1056 workspaces or it can define globs that will resolve to these same fold‐
1057 ers.
1058 In the following example, all folders located inside the folder ./pack‐
1060 ages will be treated as workspaces as long as they have valid pack‐
1061 age.json files inside them:
1062 {
1064 "name": "workspace-example",
1065 "workspaces": [
1066 "./packages/*"
1067 ]
1068 }
1069 See npm help workspaces for more examples.
1071 DEFAULT VALUES
1073 npm will default some values based on package contents.
1074 • "scripts": {"start": "node server.js"}
1076 If there is a server.js file in the root of your package, then npm will
1078 default the start command to node server.js.
1079 • "scripts":{"install": "node-gyp rebuild"}
1081 If there is a binding.gyp file in the root of your package and you have
1083 not defined an install or preinstall script, npm will default the in‐
1084 stall command to compile using node-gyp.
1085 • "contributors": [...]
1087 If there is an AUTHORS file in the root of your package, npm will treat
1089 each line as a Name <email> (url) format, where email and url are op‐
1090 tional. Lines which start with a # or are blank, will be ignored.
1091 SEE ALSO
1094 • semver ⟨https://github.com/npm/node-semver#versions⟩
1095 • npm help workspaces
1097 • npm help init
1099 • npm help version
1101 • npm help config
1103 • npm help help
1105 • npm help install
1107 • npm help publish
1109 • npm help uninstall
1111 November 2023 PACKAGE.JSON(5)