codekingpro/portable-devtools
114k
1---
2title: package.json
3section: 5
4description: Specifics of npm's package.json handling
5---
6
7### Description
8
9This document is all you need to know about what's required in your package.json file.
10It must be actual JSON, not just a JavaScript object literal.
11
12A lot of the behavior described in this document is affected by the config settings described in [`config`](/using-npm/config).
13
14### name
15
16If you plan to publish your package, the *most* important things in your package.json are the name and version fields as they will be required.
17The name and version together form an identifier that is assumed to be completely unique.
18Changes to the package should come along with changes to the version.
19If you don't plan to publish your package, the name and version fields are optional.
20
21The name is what your thing is called.
22
23Some rules:
24
25* The name must be less than or equal to 214 characters.
26 This includes the scope for scoped packages.
27* The names of scoped packages can begin with a dot or an underscore.
28 This is not permitted without a scope.
29* New packages must not have uppercase letters in the name.
30* The name ends up being part of a URL, an argument on the command line, and a folder name.
31 Therefore, the name can't contain any non-URL-safe characters.
32
33Some tips:
34
35* Don't use the same name as a core Node module.
36* Don't put "js" or "node" in the name.
37 It's assumed that it's js, since you're writing a package.json file, and you can specify the engine using the "[engines](#engines)" field.
38 (See below.)
39* The name will probably be passed as an argument to require(), so it should be something short, but also reasonably descriptive.
40* You may want to check the npm registry to see if there's something by that name already, before you get too attached to it.
41 <https://www.npmjs.com/>
42
43A name can be optionally prefixed by a scope, e.g. `@npm/example`.
44See [`scope`](/using-npm/scope) for more detail.
45
46### version
47
48If you plan to publish your package, the *most* important things in your package.json are the name and version fields as they will be required.
49The name and version together form an identifier that is assumed to be completely unique.
50Changes to the package should come along with changes to the version.
51If you don't plan to publish your package, the name and version fields are optional.
52
53Version must be parseable by [node-semver](https://github.com/npm/node-semver), which is bundled with npm as a dependency.
54(`npm install semver` to use it yourself.)
55
56### description
57
58Put a description in it.
59It's a string.
60This helps people discover your package, as it's listed in `npm search`.
61
62### keywords
63
64Put keywords in it.
65It's an array of strings.
66This helps people discover your package as it's listed in `npm search`.
67
68Example:
69
70```json
71"keywords": [
72 "node",
73 "javascript",
74 "npm"
75]
76```
77
78### homepage
79
80The URL to the project homepage.
81
82Example:
83
84```json
85"homepage": "https://github.com/npm/example#readme"
86```
87
88### bugs
89
90The URL to your project's issue tracker and / or the email address to which issues should be reported.
91These are helpful for people who encounter issues with your package.
92
93It should look like this:
94
95```json
96{
97 "bugs": {
98 "url": "https://github.com/npm/example/issues",
99 "email": "example@npmjs.com"
100 }
101}
102```
103
104You can specify either one or both values.
105If you want to provide only a URL, you can specify the value for "bugs" as a simple string instead of an object.
106
107If a URL is provided, it will be used by the `npm bugs` command.
108
109### license
110
111You should specify a license for your package so that people know how they are permitted to use it, and any restrictions you're placing on it.
112
113If you're using a common license such as BSD-2-Clause or MIT, add a current SPDX license identifier for the license you're using, like this:
114
115```json
116{
117 "license" : "BSD-3-Clause"
118}
119```
120
121You can check [the full list of SPDX license IDs](https://spdx.org/licenses/).
122Ideally, you should pick one that is [OSI](https://opensource.org/licenses/) approved.
123
124If your package is licensed under multiple common licenses, use an [SPDX license expression syntax version 2.0 string](https://spdx.dev/specifications/), like this:
125
126```json
127{
128 "license" : "(ISC OR GPL-3.0)"
129}
130```
131If you are using a license that hasn't been assigned an SPDX identifier, or if you are using a custom license, use a string value like this one:
132
133```json
134{
135 "license" : "SEE LICENSE IN <filename>"
136}
137```
138Then include a file named `<filename>` at the top level of the package.
139
140Some old packages used license objects or a "licenses" property containing an array of license objects:
141
142```json
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
166Those styles are now deprecated.
167Instead, use SPDX expressions, like this:
168
169```json
170{
171 "license": "ISC"
172}
173```
174
175```json
176{
177 "license": "(MIT OR Apache-2.0)"
178}
179```
180
181Finally, if you do not wish to grant others the right to use a private or unpublished package under any terms:
182
183```json
184{
185 "license": "UNLICENSED"
186}
187```
188
189Consider also setting `"private": true` to prevent accidental publication.
190
191### people fields: author, contributors
192
193The "author" is one person.
194"contributors" is an array of people.
195A "person" is an object with a "name" field and optionally "url" and "email", like this:
196
197```json
198{
199 "name" : "Barney Rubble",
200 "email" : "barney@npmjs.com",
201 "url" : "http://barnyrubble.npmjs.com/"
202}
203```
204
205Or you can shorten that all into a single string, and npm will parse it for you:
206
207```json
208{
209 "author": "Barney Rubble <barney@npmjs.com> (http://barnyrubble.npmjs.com/)"
210}
211```
212
213Both email and url are optional either way.
214
215npm also sets a top-level "maintainers" field with your npm user info.
216
217### funding
218
219You can specify an object containing a URL that provides up-to-date information about ways to help fund development of your package, a string URL, or an array of objects and string URLs:
220
221```json
222{
223 "funding": {
224 "type" : "individual",
225 "url" : "http://npmjs.com/donate"
226 }
227}
228```
229
230```json
231{
232 "funding": {
233 "type" : "patreon",
234 "url" : "https://www.patreon.com/user"
235 }
236}
237```
238
239```json
240{
241 "funding": "http://npmjs.com/donate"
242}
243```
244
245```json
246{
247 "funding": [
248 {
249 "type" : "individual",
250 "url" : "http://npmjs.com/donate"
251 },
252 "http://npmjs.com/donate-also",
253 {
254 "type" : "patreon",
255 "url" : "https://www.patreon.com/user"
256 }
257 ]
258}
259```
260
261Users can use the `npm fund` subcommand to list the `funding` URLs of all dependencies of their project, direct and indirect.
262A shortcut to visit each funding URL is also available when providing the project name such as:
263`npm fund <projectname>` (when there are multiple URLs, the first one will be visited)
264
265### files
266
267The optional `files` field is an array of file patterns that describes the entries to be included when your package is installed as a dependency.
268File patterns follow a similar syntax to `.gitignore`, but reversed: including a file, directory, or glob pattern (`*`, `**/*`, and such) will make it so that file is included in the tarball when it's packed.
269Omitting the field will make it default to `["*"]`, which means it will include all files.
270
271Some special files and directories are also included or excluded regardless of whether they exist in the `files` array (see below).
272
273You can also provide a `.npmignore` file in the root of your package or in subdirectories, which will keep files from being included.
274At the root of your package it will not override the "files" field, but in subdirectories it will.
275The `.npmignore` file works just like a `.gitignore`.
276If there is a `.gitignore` file, and `.npmignore` is missing, `.gitignore`'s contents will be used instead.
277
278Certain files are always included, regardless of settings:
279
280* `package.json`
281* `README`
282* `LICENSE` / `LICENCE`
283* The file in the "main" field
284* The file(s) in the "bin" field
285
286`README` & `LICENSE` can have any case and extension.
287
288Some files are always ignored by default:
289
290* `*.orig`
291* `.*.swp`
292* `.DS_Store`
293* `._*`
294* `.git`
295* `.hg`
296* `.lock-wscript`
297* `.npmrc`
298* `.svn`
299* `.wafpickle-N`
300* `CVS`
301* `config.gypi`
302* `node_modules`
303* `npm-debug.log`
304* `package-lock.json` (use [`npm-shrinkwrap.json`](/configuring-npm/npm-shrinkwrap-json) if you wish it to be published)
305* `pnpm-lock.yaml`
306* `yarn.lock`
307* `bun.lockb`
308
309Most of these ignored files can be included specifically if included in the `files` globs.
310Exceptions to this are:
311
312* `.git`
313* `.npmrc`
314* `node_modules`
315* `package-lock.json`
316* `pnpm-lock.yaml`
317* `yarn.lock`
318* `bun.lockb`
319
320These cannot be included.
321
322### exports
323
324The "exports" provides a modern alternative to "main" allowing multiple entry points to be defined, conditional entry resolution support between environments, and preventing any other entry points besides those defined in "exports". This encapsulation allows module authors to clearly define the public interface for their package.
325For more details see the [node.js documentation on package entry points](https://nodejs.org/api/packages.html#package-entry-points)
326
327### main
328
329The main field is a module ID that is the primary entry point to your program.
330That is, if your package is named `foo`, and a user installs it, and then does `require("foo")`, then your main module's exports object will be returned.
331
332This should be a module relative to the root of your package folder.
333
334For most modules, it makes the most sense to have a main script and often not much else.
335
336If `main` is not set, it defaults to `index.js` in the package's root folder.
337
338### type
339
340The `type` field defines how Node.js should interpret `.js` files in your package. This field is not used by npm.
341
342See the [Node.js documentation on the type field](https://nodejs.org/api/packages.html#type) for more information.
343
344### browser
345
346If your module is meant to be used client-side the browser field should be used instead of the main field.
347This is helpful to hint users that it might rely on primitives that aren't available in Node.js modules.
348(e.g. `window`)
349
350### bin
351
352A lot of packages have one or more executable files that they'd like to install into the PATH. npm makes this pretty easy (in fact, it uses this feature to install the "npm" executable.)
353
354To use this, supply a `bin` field in your package.json which is a map of command name to local file name.
355When this package is installed globally, that file will be either linked inside the global bins directory or a cmd (Windows Command File) will be created which executes the specified file in the `bin` field, so it is available to run by `name` or `name.cmd` (on Windows PowerShell).
356When this package is installed as a dependency in another package, the file will be linked where it will be available to that package either directly by `npm exec` or by name in other scripts when invoking them via `npm run`.
357
358
359For example, myapp could have this:
360
361```json
362{
363 "bin": {
364 "myapp": "bin/cli.js"
365 }
366}
367```
368
369So, when you install myapp, in case of unix-like OS it'll create a symlink from the `cli.js` script to `/usr/local/bin/myapp` and in case of windows it will create a cmd file usually at `C:\Users\{Username}\AppData\Roaming\npm\myapp.cmd` which runs the `cli.js` script.
370
371If you have a single executable, and its name should be the name of the package, then you can just supply it as a string.
372For example:
373
374```json
375{
376 "name": "my-program",
377 "version": "1.2.5",
378 "bin": "path/to/program"
379}
380```
381
382would be the same as this:
383
384```json
385{
386 "name": "my-program",
387 "version": "1.2.5",
388 "bin": {
389 "my-program": "path/to/program"
390 }
391}
392```
393
394Please make sure that your file(s) referenced in `bin` starts with `#!/usr/bin/env node`; otherwise, the scripts are started without the node executable!
395
396Note that you can also set the executable files using [directories.bin](#directoriesbin).
397
398See [folders](/configuring-npm/folders#executables) for more info on executables.
399
400### man
401
402Specify either a single file or an array of filenames to put in place for the `man` program to find.
403
404If only a single file is provided, then it's installed such that it is the result from `man <pkgname>`, regardless of its actual filename.
405For example:
406
407```json
408{
409 "name": "foo",
410 "version": "1.2.3",
411 "description": "A packaged foo fooer for fooing foos",
412 "main": "foo.js",
413 "man": "./man/doc.1"
414}
415```
416
417would link the `./man/doc.1` file in such that it is the target for `man foo`
418
419If the filename doesn't start with the package name, then it's prefixed.
420So, this:
421
422```json
423{
424 "name": "foo",
425 "version": "1.2.3",
426 "description": "A packaged foo fooer for fooing foos",
427 "main": "foo.js",
428 "man": [
429 "./man/foo.1",
430 "./man/bar.1"
431 ]
432}
433```
434
435will create files to do `man foo` and `man foo-bar`.
436
437Man files must end with a number, and optionally a `.gz` suffix if they are compressed.
438The number dictates which man section the file is installed into.
439
440```json
441{
442 "name": "foo",
443 "version": "1.2.3",
444 "description": "A packaged foo fooer for fooing foos",
445 "main": "foo.js",
446 "man": [
447 "./man/foo.1",
448 "./man/foo.2"
449 ]
450}
451```
452
453will create entries for `man foo` and `man 2 foo`
454
455### directories
456
457The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec details a few ways that you can indicate the structure of your package using a `directories` object.
458If you look at [npm's package.json](https://registry.npmjs.org/npm/latest), you'll see that it has directories for doc, lib, and man.
459
460In the future, this information may be used in other creative ways.
461
462#### directories.bin
463
464If you specify a `bin` directory in `directories.bin`, all the files in that folder will be added.
465
466Because of the way the `bin` directive works, specifying both a `bin` path and setting `directories.bin` is an error.
467If you want to specify individual files, use `bin`, and for all the files in an existing `bin` directory, use `directories.bin`.
468
469#### directories.man
470
471A folder that is full of man pages.
472Sugar to generate a "man" array by walking the folder.
473
474### repository
475
476Specify the place where your code lives.
477This is helpful for people who want to contribute.
478If the git repo is on GitHub, then the `npm repo` command will be able to find you.
479
480Do it like this:
481
482```json
483{
484 "repository": {
485 "type": "git",
486 "url": "git+https://github.com/npm/cli.git"
487 }
488}
489```
490
491The URL should be a publicly available (perhaps read-only) URL that can be handed directly to a VCS program without any modification.
492It should not be a URL to an html project page that you put in your browser.
493It's for computers.
494
495For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same shortcut syntax you use for `npm install`:
496
497```json
498{
499 "repository": "npm/example",
500
501 "repository": "github:npm/example",
502
503 "repository": "gist:11081aaa281",
504
505 "repository": "bitbucket:user/repo",
506
507 "repository": "gitlab:user/repo"
508}
509```
510
511**Note on normalization:** When you publish a package, npm normalizes the `repository` field to the full object format with a `url` property. If you use a shorthand format (like `"npm/example"`), you'll see a warning during `npm publish` indicating that the field was auto-corrected. While the shorthand format currently works, it's recommended to use the full object format in your `package.json` to avoid warnings and ensure future compatibility:
512
513```json
514{
515 "repository": {
516 "type": "git",
517 "url": "git+https://github.com/npm/example.git"
518 }
519}
520```
521
522You can run `npm pkg fix` to automatically convert shorthand formats to the normalized object format.
523
524If the `package.json` for your package is not in the root directory (for example if it is part of a monorepo), you can specify the directory in which it lives:
525
526```json
527{
528 "repository": {
529 "type": "git",
530 "url": "git+https://github.com/npm/cli.git",
531 "directory": "workspaces/libnpmpublish"
532 }
533}
534```
535
536### scripts
537
538The "scripts" property is a dictionary containing script commands that are run at various times in the lifecycle of your package.
539The key is the lifecycle event, and the value is the command to run at that point.
540
541See [`scripts`](/using-npm/scripts) to find out more about writing package scripts.
542
543### gypfile
544
545If you have a binding.gyp file in the root of your package and you have not defined your own `install` or `preinstall` scripts, npm will default to building your module using node-gyp.
546
547To prevent npm from automatically building your module with node-gyp, set `gypfile` to `false`:
548
549```json
550{
551 "gypfile": false
552}
553```
554
555This is useful for packages that include native addons but want to handle the build process differently, or packages that have a binding.gyp file but should not be built as a native addon.
556
557### config
558
559A "config" object can be used to set configuration parameters used in package scripts that persist across upgrades.
560For instance, if a package had the following:
561
562```json
563{
564 "name": "foo",
565 "config": {
566 "port": "8080"
567 }
568}
569```
570
571It could also have a "start" script that referenced the `npm_package_config_port` environment variable.
572
573### dependencies
574
575Dependencies are specified in a simple object that maps a package name to a version range.
576The version range is a string which has one or more space-separated descriptors.
577Dependencies can also be identified with a tarball or git URL.
578
579**Please do not put test harnesses or transpilers or other "development" time tools in your `dependencies` object.**
580See `devDependencies`, below.
581
582See [semver](https://github.com/npm/node-semver#versions) for more details about specifying version ranges.
583
584* `version` Must match `version` exactly
585* `>version` Must be greater than `version`
586* `>=version` etc
587* `<version`
588* `<=version`
589* `~version` "Approximately equivalent to version" See [semver](https://github.com/npm/node-semver#versions)
590* `^version` "Compatible with version" See [semver](https://github.com/npm/node-semver#versions)
591* `1.2.x` 1.2.0, 1.2.1, etc., but not 1.3.0
592* `http://...` See 'URLs as Dependencies' below
593* `*` Matches any version
594* `""` (just an empty string) Same as `*`
595* `version1 - version2` Same as `>=version1 <=version2`.
596* `range1 || range2` Passes if either range1 or range2 are satisfied.
597* `git...` See 'Git URLs as Dependencies' below
598* `user/repo` See 'GitHub URLs' below
599* `tag` A specific version tagged and published as `tag` See [`npm dist-tag`](/commands/npm-dist-tag)
600* `path/path/path` See [Local Paths](#local-paths) below
601* `npm:@scope/pkg@version` Custom alias for a package See [`package-spec`](/using-npm/package-spec#aliases)
602
603For example, these are all valid:
604
605```json
606{
607 "dependencies": {
608 "foo": "1.0.0 - 2.9999.9999",
609 "bar": ">=1.0.2 <2.1.2",
610 "baz": ">1.0.2 <=2.3.4",
611 "boo": "2.0.1",
612 "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",
613 "asd": "http://npmjs.com/example.tar.gz",
614 "til": "~1.2",
615 "elf": "~1.2.3",
616 "two": "2.x",
617 "thr": "3.3.x",
618 "lat": "latest",
619 "dyl": "file:../dyl",
620 "kpg": "npm:pkg@1.0.0"
621 }
622}
623```
624
625#### URLs as Dependencies
626
627You may specify a tarball URL in place of a version range.
628
629This tarball will be downloaded and installed locally to your package at install time.
630
631#### Git URLs as Dependencies
632
633Git URLs are of the form:
634
635```bash
636<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]
637```
638
639`<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or `git+file`.
640
641If `#<commit-ish>` is provided, it will be used to clone exactly that commit.
642If the commit-ish has the format `#semver:<semver>`, `<semver>` can be any valid semver range or exact version, and npm will look for any tags or refs matching that range in the remote repository, much as it would for a registry dependency.
643If neither `#<commit-ish>` or `#semver:<semver>` is specified, then the default branch is used.
644
645Examples:
646
647```bash
648git+ssh://git@github.com:npm/cli.git#v1.0.27
649git+ssh://git@github.com:npm/cli#semver:^5.0
650git+https://isaacs@github.com/npm/cli.git
651git://github.com/npm/cli.git#v1.0.27
652```
653
654When installing from a `git` repository, the presence of certain fields in the `package.json` will cause npm to believe it needs to perform a build.
655To do so your repository will be cloned into a temporary directory, all of its deps installed, relevant scripts run, and the resulting directory packed and installed.
656
657This flow will occur if your git dependency uses `workspaces`, or if any of the following scripts are present:
658
659* `build`
660* `prepare`
661* `prepack`
662* `preinstall`
663* `install`
664* `postinstall`
665
666If your git repository includes pre-built artifacts, you will likely want to make sure that none of the above scripts are defined, or your dependency will be rebuilt for every installation.
667
668#### GitHub URLs
669
670As of version 1.1.65, you can refer to GitHub URLs as just "foo":
671"user/foo-project". Just as with git URLs, a `commit-ish` suffix can be included.
672For example:
673
674```json
675{
676 "name": "foo",
677 "version": "0.0.0",
678 "dependencies": {
679 "express": "expressjs/express",
680 "mocha": "mochajs/mocha#4727d357ea",
681 "module": "npm/example-github-repo#feature\/branch"
682 }
683}
684```
685
686#### Local Paths
687
688As of version 2.0.0 you can provide a path to a local directory that contains a package.
689Local paths can be saved using `npm install -S` or `npm install --save`, using any of these forms:
690
691```bash
692../foo/bar
693~/foo/bar
694./foo/bar
695/foo/bar
696```
697
698in which case they will be normalized to a relative path and added to your `package.json`.
699For example:
700
701```json
702{
703 "name": "baz",
704 "dependencies": {
705 "bar": "file:../foo/bar"
706 }
707}
708```
709
710This feature is helpful for local offline development and creating tests that require npm installing where you don't want to hit an external server, but should not be used when publishing your package to the public registry.
711
712*note*: Packages linked by local path will not have their own dependencies installed when `npm install` is run.
713You must run `npm install` from inside the local path itself.
714
715### devDependencies
716
717If someone is planning on downloading and using your module in their program, then they probably don't want or need to download and build the external test or documentation framework that you use.
718
719In this case, it's best to map these additional items in a `devDependencies` object.
720
721These things will be installed when doing `npm link` or `npm install` from the root of a package, and can be managed like any other npm configuration param.
722See [`config`](/using-npm/config) for more on the topic.
723
724For build steps that are not platform-specific, such as compiling CoffeeScript or other languages to JavaScript, use the `prepare` script to do this, and make the required package a devDependency.
725
726For example:
727
728```json
729{
730 "name": "@npm/ethopia-waza",
731 "description": "a delightfully fruity coffee varietal",
732 "version": "1.2.3",
733 "devDependencies": {
734 "coffee-script": "~1.6.3"
735 },
736 "scripts": {
737 "prepare": "coffee -o lib/ -c src/waza.coffee"
738 },
739 "main": "lib/waza.js"
740}
741```
742
743The `prepare` script will be run before publishing, so that users can consume the functionality without requiring them to compile it themselves.
744In dev mode (ie, locally running `npm install`), it'll run this script as well, so that you can test it easily.
745
746### peerDependencies
747
748In some cases, you want to express the compatibility of your package with a host tool or library, while not necessarily doing a `require` of this host.
749This is usually referred to as a *plugin*. Notably, your module may be exposing a specific interface, expected and specified by the host documentation.
750
751For example:
752
753```json
754{
755 "name": "@npm/tea-latte",
756 "version": "1.3.5",
757 "peerDependencies": {
758 "@npm/tea": "2.x"
759 }
760}
761```
762
763This ensures your package `@npm/tea-latte` can be installed *along* with the second major version of the host package `@npm/tea` only.
764`npm install tea-latte` could possibly yield the following dependency graph:
765
766```bash
767├── @npm/tea-latte@1.3.5
768└── @npm/tea@2.2.0
769```
770
771In npm versions 3 through 6, `peerDependencies` were not automatically installed, and would raise a warning if an invalid version of the peer dependency was found in the tree.
772As of npm v7, peerDependencies _are_ installed by default.
773
774Trying to install another plugin with a conflicting requirement may cause an error if the tree cannot be resolved correctly.
775For this reason, make sure your plugin requirement is as broad as possible, and not to lock it down to specific patch versions.
776
777Assuming the host complies with [semver](https://semver.org/), only changes in the host package's major version will break your plugin.
778Thus, if you've worked with every 1.x version of the host package, use `"^1.0"` or `"1.x"` to express this.
779If you depend on features introduced in 1.5.2, use `"^1.5.2"`.
780
781### peerDependenciesMeta
782
783The `peerDependenciesMeta` field serves to provide npm more information on how your peer dependencies are to be used.
784Specifically, it allows peer dependencies to be marked as optional.
785Npm will not automatically install optional peer dependencies.
786This allows you to integrate and interact with a variety of host packages without requiring all of them to be installed.
787
788For example:
789
790```json
791{
792 "name": "@npm/tea-latte",
793 "version": "1.3.5",
794 "peerDependencies": {
795 "@npm/tea": "2.x",
796 "@npm/soy-milk": "1.2"
797 },
798 "peerDependenciesMeta": {
799 "@npm/soy-milk": {
800 "optional": true
801 }
802 }
803}
804```
805
806### bundleDependencies
807
808This defines an array of package names that will be bundled when publishing the package.
809
810In cases where you need to preserve npm packages locally or have them available through a single file download, you can bundle the packages in a tarball file by specifying the package names in the `bundleDependencies` array and executing `npm pack`.
811
812For example:
813
814If we define a package.json like this:
815
816```json
817{
818 "name": "@npm/awesome-web-framework",
819 "version": "1.0.0",
820 "bundleDependencies": [
821 "@npm/renderized",
822 "@npm/super-streams"
823 ]
824}
825```
826
827we can obtain `@npm/awesome-web-framework-1.0.0.tgz` file by running `npm pack`.
828This file contains the dependencies `@npm/renderized` and `@npm/super-streams` which can be installed in a new project by executing `npm install awesome-web-framework-1.0.0.tgz`.
829Note that the package names do not include any versions, as that information is specified in `dependencies`.
830
831If this is spelled `"bundledDependencies"`, then that is also honored.
832
833Alternatively, `"bundleDependencies"` can be defined as a boolean value.
834A value of `true` will bundle all dependencies, a value of `false` will bundle none.
835
836### optionalDependencies
837
838If a dependency can be used, but you would like npm to proceed if it cannot be found or fails to install, then you may put it in the `optionalDependencies` object.
839This is a map of package name to version or URL, just like the `dependencies` object.
840The difference is that build failures do not cause installation to fail.
841Running `npm install --omit=optional` will prevent these dependencies from being installed.
842
843It is still your program's responsibility to handle the lack of the dependency.
844For example, something like this:
845
846```js
847try {
848 var foo = require('@npm/foo')
849 var fooVersion = require('@npm/foo/package.json').version
850} catch (er) {
851 foo = null
852}
853if ( notGoodFooVersion(fooVersion) ) {
854 foo = null
855}
856
857// .. then later in your program ..
858
859if (foo) {
860 foo.doFooThings()
861}
862```
863
864Entries in `optionalDependencies` will override entries of the same name in `dependencies`, so it's usually best to only put in one place.
865
866### overrides
867
868If you need to make specific changes to dependencies of your dependencies, for example replacing the version of a dependency with a known security issue, replacing an existing dependency with a fork, or making sure that the same version of a package is used everywhere, then you may add an override.
869
870Overrides provide a way to replace a package in your dependency tree with another version, or another package entirely.
871These changes can be scoped as specific or as vague as desired.
872
873Overrides are only considered in the root `package.json` file for a project.
874Overrides in installed dependencies (including [workspaces](/using-npm/workspaces)) are not considered in dependency tree resolution.
875Published packages may dictate their resolutions by pinning dependencies or using an [`npm-shrinkwrap.json`](/configuring-npm/npm-shrinkwrap-json) file.
876
877To make sure the package `@npm/foo` is always installed as version `1.0.0` no matter what version your dependencies rely on:
878
879```json
880{
881 "overrides": {
882 "@npm/foo": "1.0.0"
883 }
884}
885```
886
887The above is a short hand notation, the full object form can be used to allow overriding a package itself as well as a child of the package.
888This will cause `@npm/foo` to always be `1.0.0` while also making `@npm/bar` at any depth beyond `@npm/foo` also `1.0.0`:
889
890```json
891{
892 "overrides": {
893 "@npm/foo": {
894 ".": "1.0.0",
895 "@npm/bar": "1.0.0"
896 }
897 }
898}
899```
900
901To only override `@npm/foo` to be `1.0.0` when it's a child (or grandchild, or great grandchild, etc) of the package `@npm/bar`:
902
903```json
904{
905 "overrides": {
906 "@npm/bar": {
907 "@npm/foo": "1.0.0"
908 }
909 }
910}
911```
912
913Keys can be nested to any arbitrary length.
914To override `@npm/foo` only when it's a child of `@npm/bar` and only when `@npm/bar` is a child of `@npm/baz`:
915
916```json
917{
918 "overrides": {
919 "@npm/baz": {
920 "@npm/bar": {
921 "@npm/foo": "1.0.0"
922 }
923 }
924 }
925}
926```
927
928The key of an override can also include a version, or range of versions.
929To override `@npm/foo` to `1.0.0`, but only when it's a child of `@npm/bar@2.0.0`:
930
931```json
932{
933 "overrides": {
934 "@npm/bar@2.0.0": {
935 "@npm/foo": "1.0.0"
936 }
937 }
938}
939```
940
941You may not set an override for a package that you directly depend on unless both the dependency and the override itself share the exact same spec.
942To make this limitation easier to deal with, overrides may also be defined as a reference to a spec for a direct dependency by prefixing the name of the package you wish the version to match with a `$`.
943
944```json
945{
946 "dependencies": {
947 "@npm/foo": "^1.0.0"
948 },
949 "overrides": {
950 // BAD, will throw an EOVERRIDE error
951 // "foo": "^2.0.0"
952 // GOOD, specs match so override is allowed
953 // "foo": "^1.0.0"
954 // BEST, the override is defined as a reference to the dependency
955 "@npm/foo": "$foo",
956 // the referenced package does not need to match the overridden one
957 "@npm/bar": "$foo"
958 }
959}
960```
961
962#### Replacing a dependency with a fork
963
964You can replace a package with a different package or fork using several methods:
965
966**Using the `npm:` prefix to replace with a different package name:**
967
968```json
969{
970 "overrides": {
971 "package-name": "npm:@scope/forked-package@1.0.0"
972 }
973}
974```
975
976**Using a GitHub repository (supports branches, tags, or commit hashes):**
977
978```json
979{
980 "overrides": {
981 "package-name": "github:username/repo#branch-name"
982 }
983}
984```
985
986**Using a local file path:**
987
988```json
989{
990 "overrides": {
991 "package-name": "file:../local-fork"
992 }
993}
994```
995
996These replacement methods work for both top-level overrides and nested overrides.
997For example, to replace a transitive dependency with a fork:
998
999```json
1000{
1001 "overrides": {
1002 "parent-package": {
1003 "vulnerable-dep": "github:username/patched-fork#v2.0.1"
1004 }
1005 }
1006}
1007```
1008
1009### engines
1010
1011You can specify the version of node that your stuff works on:
1012
1013```json
1014{
1015 "engines": {
1016 "node": ">=0.10.3 <15"
1017 }
1018}
1019```
1020
1021And, like with dependencies, if you don't specify the version (or if you specify "\*" as the version), then any version of node will do.
1022
1023You can also use the "engines" field to specify which versions of npm are capable of properly installing your program.
1024For example:
1025
1026```json
1027{
1028 "engines": {
1029 "npm": "~1.0.20"
1030 }
1031}
1032```
1033
1034Unless the user has set the [`engine-strict` config](/using-npm/config#engine-strict) flag, this field is advisory only and will only produce warnings when your package is installed as a dependency.
1035
1036### os
1037
1038You can specify which operating systems your module will run on:
1039
1040```json
1041{
1042 "os": [
1043 "darwin",
1044 "linux"
1045 ]
1046}
1047```
1048
1049You can also block instead of allowing operating systems, just prepend the blocked os with a '!':
1050
1051```json
1052{
1053 "os": [
1054 "!win32"
1055 ]
1056}
1057```
1058
1059The host operating system is determined by `process.platform`
1060
1061It is allowed to both block and allow an item, although there isn't any good reason to do this.
1062
1063### cpu
1064
1065If your code only runs on certain cpu architectures, you can specify which ones.
1066
1067```json
1068{
1069 "cpu": [
1070 "x64",
1071 "ia32"
1072 ]
1073}
1074```
1075
1076Like the `os` option, you can also block architectures:
1077
1078```json
1079{
1080 "cpu": [
1081 "!arm",
1082 "!mips"
1083 ]
1084}
1085```
1086
1087The host architecture is determined by `process.arch`
1088
1089### libc
1090
1091If your code only runs or builds in certain versions of libc, you can specify which ones.
1092This field only applies if `os` is `linux`.
1093
1094```json
1095{
1096 "os": "linux",
1097 "libc": "glibc"
1098}
1099```
1100
1101### devEngines
1102
1103The `devEngines` field aids engineers working on a codebase to all be using the same tooling.
1104
1105You can specify a `devEngines` property in your `package.json` which will run before `install`, `ci`, and `run` commands.
1106
1107
1108> Note: `engines` and `devEngines` differ in object shape.
1109They also function very differently.
1110`engines` is designed to alert the user when a dependency uses a different npm or node version than the project it's being used in, whereas `devEngines` is used to alert people interacting with the source code of a project.
1111
1112The supported keys under the `devEngines` property are `cpu`, `os`, `libc`, `runtime`, and `packageManager`.
1113Each property can be an object or an array of objects.
1114Objects must contain `name`, and optionally can specify `version`, and `onFail`.
1115`onFail` can be `warn`, `error`, or `ignore`, and if left undefined is of the same value as `error`.
1116`npm` will assume that you're running with `node`.
1117Here's an example of a project that will fail if the environment is not `node` and `npm`.
1118If you set `runtime.name` or `packageManager.name` to any other string, it will fail within the npm CLI.
1119
1120```json
1121{
1122 "devEngines": {
1123 "runtime": {
1124 "name": "node",
1125 "onFail": "error"
1126 },
1127 "packageManager": {
1128 "name": "npm",
1129 "onFail": "error"
1130 }
1131 }
1132}
1133```
1134
1135### private
1136
1137If you set `"private": true` in your package.json, then npm will refuse to publish it.
1138
1139This is a way to prevent accidental publication of private repositories.
1140If you would like to ensure that a given package is only ever published to a specific registry (for example, an internal registry), then use the `publishConfig` dictionary described below to override the `registry` config param at publish-time.
1141
1142### publishConfig
1143
1144This is a set of config values that will be used at publish-time.
1145It's especially handy if you want to set the tag, registry or access, so that you can ensure that a given package is not tagged with "latest", published to the global public registry or that a scoped module is private by default.
1146
1147See [`config`](/using-npm/config) to see the list of config options that can be overridden.
1148
1149### workspaces
1150
1151The optional `workspaces` field is an array of file patterns that describes locations within the local file system that the install client should look up to find each [workspace](/using-npm/workspaces) that needs to be symlinked to the top level `node_modules` folder.
1152
1153It can describe either the direct paths of the folders to be used as workspaces or it can define globs that will resolve to these same folders.
1154
1155In the following example, all folders located inside the folder `./packages` will be treated as workspaces as long as they have valid `package.json` files inside them:
1156
1157```json
1158{
1159 "name": "workspace-example",
1160 "workspaces": [
1161 "./packages/*"
1162 ]
1163}
1164```
1165
1166See [`workspaces`](/using-npm/workspaces) for more examples.
1167
1168### DEFAULT VALUES
1169
1170npm will default some values based on package contents.
1171
1172* `"scripts": {"start": "node server.js"}`
1173
1174 If there is a `server.js` file in the root of your package, then npm will default the `start` command to `node server.js`.
1175
1176* `"scripts":{"install": "node-gyp rebuild"}`
1177
1178 If there is a `binding.gyp` file in the root of your package and you have not defined an `install` or `preinstall` script, npm will default the `install` command to compile using node-gyp.
1179
1180* `"contributors": [...]`
1181
1182 If there is an `AUTHORS` file in the root of your package, npm will treat each line as a `Name <email> (url)` format, where email and url are optional.
1183 Lines which start with a `#` or are blank, will be ignored.
1184
1185### SEE ALSO
1186
1187* [semver](https://github.com/npm/node-semver#versions)
1188* [workspaces](/using-npm/workspaces)
1189* [npm init](/commands/npm-init)
1190* [npm version](/commands/npm-version)
1191* [npm config](/commands/npm-config)
1192* [npm help](/commands/npm-help)
1193* [npm install](/commands/npm-install)
1194* [npm publish](/commands/npm-publish)
1195* [npm uninstall](/commands/npm-uninstall)
1196