|
|
- .TH "PACKAGE\.JSON" "5" "August 2018" "" ""
- .SH "NAME"
- \fBpackage.json\fR \- Specifics of npm's package\.json handling
- .SH DESCRIPTION
- .P
- This document is all you need to know about what's required in your package\.json
- file\. It must be actual JSON, not just a JavaScript object literal\.
- .P
- A lot of the behavior described in this document is affected by the config
- settings described in npm help 7 \fBnpm\-config\fP\|\.
- .SH name
- .P
- If you plan to publish your package, the \fImost\fR important things in your
- package\.json are the name and version fields as they will be required\. The name
- and version together form an identifier that is assumed to be completely unique\.
- Changes to the package should come along with changes to the version\. If you don't
- plan to publish your package, the name and version fields are optional\.
- .P
- The name is what your thing is called\.
- .P
- Some rules:
- .RS 0
- .IP \(bu 2
- The name must be less than or equal to 214 characters\. This includes the scope for
- scoped packages\.
- .IP \(bu 2
- The name can't start with a dot or an underscore\.
- .IP \(bu 2
- New packages must not have uppercase letters in the name\.
- .IP \(bu 2
- The name ends up being part of a URL, an argument on the command line, and a
- folder name\. Therefore, the name can't contain any non\-URL\-safe characters\.
-
- .RE
- .P
- Some tips:
- .RS 0
- .IP \(bu 2
- Don't use the same name as a core Node module\.
- .IP \(bu 2
- Don't put "js" or "node" in the name\. It's assumed that it's js, since you're
- writing a package\.json file, and you can specify the engine using the "engines"
- field\. (See below\.)
- .IP \(bu 2
- The name will probably be passed as an argument to require(), so it should
- be something short, but also reasonably descriptive\.
- .IP \(bu 2
- 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\. https://www\.npmjs\.com/
-
- .RE
- .P
- A name can be optionally prefixed by a scope, e\.g\. \fB@myorg/mypackage\fP\|\. See
- npm help 7 \fBnpm\-scope\fP for more detail\.
- .SH version
- .P
- If you plan to publish your package, the \fImost\fR important things in your
- package\.json are the name and version fields as they will be required\. The name
- and version together form an identifier that is assumed to be completely unique\.
- Changes to the package should come along with changes to the version\. If you don't
- plan to publish your package, the name and version fields are optional\.
- .P
- Version must be parseable by
- node\-semver \fIhttps://github\.com/isaacs/node\-semver\fR, which is bundled
- with npm as a dependency\. (\fBnpm install semver\fP to use it yourself\.)
- .P
- More on version numbers and ranges at npm help 7 semver\.
- .SH description
- .P
- Put a description in it\. It's a string\. This helps people discover your
- package, as it's listed in \fBnpm search\fP\|\.
- .SH keywords
- .P
- Put keywords in it\. It's an array of strings\. This helps people
- discover your package as it's listed in \fBnpm search\fP\|\.
- .SH homepage
- .P
- The url to the project homepage\.
- .P
- Example:
- .P
- .RS 2
- .nf
- "homepage": "https://github\.com/owner/project#readme"
- .fi
- .RE
- .SH bugs
- .P
- The url to your project's issue tracker and / or the email address to which
- issues should be reported\. These are helpful for people who encounter issues
- with your package\.
- .P
- It should look like this:
- .P
- .RS 2
- .nf
- { "url" : "https://github\.com/owner/project/issues"
- , "email" : "project@hostname\.com"
- }
- .fi
- .RE
- .P
- You can specify either one or both values\. If you want to provide only a url,
- you can specify the value for "bugs" as a simple string instead of an object\.
- .P
- If a url is provided, it will be used by the \fBnpm bugs\fP command\.
- .SH license
- .P
- You 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\.
- .P
- If 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:
- .P
- .RS 2
- .nf
- { "license" : "BSD\-3\-Clause" }
- .fi
- .RE
- .P
- You can check the full list of SPDX license IDs \fIhttps://spdx\.org/licenses/\fR\|\.
- Ideally you should pick one that is
- OSI \fIhttps://opensource\.org/licenses/alphabetical\fR approved\.
- .P
- If your package is licensed under multiple common licenses, use an SPDX license
- expression syntax version 2\.0 string \fIhttps://www\.npmjs\.com/package/spdx\fR, like this:
- .P
- .RS 2
- .nf
- { "license" : "(ISC OR GPL\-3\.0)" }
- .fi
- .RE
- .P
- If 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:
- .P
- .RS 2
- .nf
- { "license" : "SEE LICENSE IN <filename>" }
- .fi
- .RE
- .P
- Then include a file named \fB<filename>\fP at the top level of the package\.
- .P
- Some old packages used license objects or a "licenses" property containing an
- array of license objects:
- .P
- .RS 2
- .nf
- // Not valid metadata
- { "license" :
- { "type" : "ISC"
- , "url" : "https://opensource\.org/licenses/ISC"
- }
- }
-
- // Not valid metadata
- { "licenses" :
- [
- { "type": "MIT"
- , "url": "https://www\.opensource\.org/licenses/mit\-license\.php"
- }
- , { "type": "Apache\-2\.0"
- , "url": "https://opensource\.org/licenses/apache2\.0\.php"
- }
- ]
- }
- .fi
- .RE
- .P
- Those styles are now deprecated\. Instead, use SPDX expressions, like this:
- .P
- .RS 2
- .nf
- { "license": "ISC" }
-
- { "license": "(MIT OR Apache\-2\.0)" }
- .fi
- .RE
- .P
- Finally, if you do not wish to grant others the right to use a private or
- unpublished package under any terms:
- .P
- .RS 2
- .nf
- { "license": "UNLICENSED" }
- .fi
- .RE
- .P
- Consider also setting \fB"private": true\fP to prevent accidental publication\.
- .SH people fields: author, contributors
- .P
- The "author" is one person\. "contributors" is an array of people\. A "person"
- is an object with a "name" field and optionally "url" and "email", like this:
- .P
- .RS 2
- .nf
- { "name" : "Barney Rubble"
- , "email" : "b@rubble\.com"
- , "url" : "http://barnyrubble\.tumblr\.com/"
- }
- .fi
- .RE
- .P
- Or you can shorten that all into a single string, and npm will parse it for you:
- .P
- .RS 2
- .nf
- "Barney Rubble <b@rubble\.com> (http://barnyrubble\.tumblr\.com/)"
- .fi
- .RE
- .P
- Both email and url are optional either way\.
- .P
- npm also sets a top\-level "maintainers" field with your npm user info\.
- .SH files
- .P
- The optional \fBfiles\fP field is an array of file patterns that describes
- the entries to be included when your package is installed as a
- dependency\. File patterns follow a similar syntax to \fB\|\.gitignore\fP, but
- reversed: including a file, directory, or glob pattern (\fB*\fP, \fB**/*\fP, and such)
- will make it so that file is included in the tarball when it's packed\. Omitting
- the field will make it default to \fB["*"]\fP, which means it will include all files\.
- .P
- Some special files and directories are also included or excluded regardless of
- whether they exist in the \fBfiles\fP array (see below)\.
- .P
- You can also provide a \fB\|\.npmignore\fP file in the root of your package or
- in subdirectories, which will keep files from being included\. At the
- root of your package it will not override the "files" field, but in
- subdirectories it will\. The \fB\|\.npmignore\fP file works just like a
- \fB\|\.gitignore\fP\|\. If there is a \fB\|\.gitignore\fP file, and \fB\|\.npmignore\fP is
- missing, \fB\|\.gitignore\fP\|'s contents will be used instead\.
- .P
- Files included with the "package\.json#files" field \fIcannot\fR be excluded
- through \fB\|\.npmignore\fP or \fB\|\.gitignore\fP\|\.
- .P
- Certain files are always included, regardless of settings:
- .RS 0
- .IP \(bu 2
- \fBpackage\.json\fP
- .IP \(bu 2
- \fBREADME\fP
- .IP \(bu 2
- \fBCHANGES\fP / \fBCHANGELOG\fP / \fBHISTORY\fP
- .IP \(bu 2
- \fBLICENSE\fP / \fBLICENCE\fP
- .IP \(bu 2
- \fBNOTICE\fP
- .IP \(bu 2
- The file in the "main" field
-
- .RE
- .P
- \fBREADME\fP, \fBCHANGES\fP, \fBLICENSE\fP & \fBNOTICE\fP can have any case and extension\.
- .P
- Conversely, some files are always ignored:
- .RS 0
- .IP \(bu 2
- \fB\|\.git\fP
- .IP \(bu 2
- \fBCVS\fP
- .IP \(bu 2
- \fB\|\.svn\fP
- .IP \(bu 2
- \fB\|\.hg\fP
- .IP \(bu 2
- \fB\|\.lock\-wscript\fP
- .IP \(bu 2
- \fB\|\.wafpickle\-N\fP
- .IP \(bu 2
- \fB\|\.*\.swp\fP
- .IP \(bu 2
- \fB\|\.DS_Store\fP
- .IP \(bu 2
- \fB\|\._*\fP
- .IP \(bu 2
- \fBnpm\-debug\.log\fP
- .IP \(bu 2
- \fB\|\.npmrc\fP
- .IP \(bu 2
- \fBnode_modules\fP
- .IP \(bu 2
- \fBconfig\.gypi\fP
- .IP \(bu 2
- \fB*\.orig\fP
- .IP \(bu 2
- \fBpackage\-lock\.json\fP (use shrinkwrap instead)
-
- .RE
- .SH main
- .P
- The main field is a module ID that is the primary entry point to your program\.
- That is, if your package is named \fBfoo\fP, and a user installs it, and then does
- \fBrequire("foo")\fP, then your main module's exports object will be returned\.
- .P
- This should be a module ID relative to the root of your package folder\.
- .P
- For most modules, it makes the most sense to have a main script and often not
- much else\.
- .SH browser
- .P
- If your module is meant to be used client\-side the browser field should be
- used instead of the main field\. This is helpful to hint users that it might
- rely on primitives that aren't available in Node\.js modules\. (e\.g\. \fBwindow\fP)
- .SH bin
- .P
- A 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\.)
- .P
- To use this, supply a \fBbin\fP field in your package\.json which is a map of
- command name to local file name\. On install, npm will symlink that file into
- \fBprefix/bin\fP for global installs, or \fB\|\./node_modules/\.bin/\fP for local
- installs\.
- .P
- For example, myapp could have this:
- .P
- .RS 2
- .nf
- { "bin" : { "myapp" : "\./cli\.js" } }
- .fi
- .RE
- .P
- So, when you install myapp, it'll create a symlink from the \fBcli\.js\fP script to
- \fB/usr/local/bin/myapp\fP\|\.
- .P
- If you have a single executable, and its name should be the name
- of the package, then you can just supply it as a string\. For example:
- .P
- .RS 2
- .nf
- { "name": "my\-program"
- , "version": "1\.2\.5"
- , "bin": "\./path/to/program" }
- .fi
- .RE
- .P
- would be the same as this:
- .P
- .RS 2
- .nf
- { "name": "my\-program"
- , "version": "1\.2\.5"
- , "bin" : { "my\-program" : "\./path/to/program" } }
- .fi
- .RE
- .P
- Please make sure that your file(s) referenced in \fBbin\fP starts with
- \fB#!/usr/bin/env node\fP, otherwise the scripts are started without the node
- executable!
- .SH man
- .P
- Specify either a single file or an array of filenames to put in place for the
- \fBman\fP program to find\.
- .P
- If only a single file is provided, then it's installed such that it is the
- result from \fBman <pkgname>\fP, regardless of its actual filename\. For example:
- .P
- .RS 2
- .nf
- { "name" : "foo"
- , "version" : "1\.2\.3"
- , "description" : "A packaged foo fooer for fooing foos"
- , "main" : "foo\.js"
- , "man" : "\./man/doc\.1"
- }
- .fi
- .RE
- .P
- would link the \fB\|\./man/doc\.1\fP file in such that it is the target for \fBman foo\fP
- .P
- If the filename doesn't start with the package name, then it's prefixed\.
- So, this:
- .P
- .RS 2
- .nf
- { "name" : "foo"
- , "version" : "1\.2\.3"
- , "description" : "A packaged foo fooer for fooing foos"
- , "main" : "foo\.js"
- , "man" : [ "\./man/foo\.1", "\./man/bar\.1" ]
- }
- .fi
- .RE
- .P
- will create files to do \fBman foo\fP and \fBman foo\-bar\fP\|\.
- .P
- Man files must end with a number, and optionally a \fB\|\.gz\fP suffix if they are
- compressed\. The number dictates which man section the file is installed into\.
- .P
- .RS 2
- .nf
- { "name" : "foo"
- , "version" : "1\.2\.3"
- , "description" : "A packaged foo fooer for fooing foos"
- , "main" : "foo\.js"
- , "man" : [ "\./man/foo\.1", "\./man/foo\.2" ]
- }
- .fi
- .RE
- .P
- will create entries for \fBman foo\fP and \fBman 2 foo\fP
- .SH directories
- .P
- The CommonJS Packages \fIhttp://wiki\.commonjs\.org/wiki/Packages/1\.0\fR spec details a
- few ways that you can indicate the structure of your package using a \fBdirectories\fP
- object\. If you look at npm's package\.json \fIhttps://registry\.npmjs\.org/npm/latest\fR,
- you'll see that it has directories for doc, lib, and man\.
- .P
- In the future, this information may be used in other creative ways\.
- .SS directories\.lib
- .P
- Tell people where the bulk of your library is\. Nothing special is done
- with the lib folder in any way, but it's useful meta info\.
- .SS directories\.bin
- .P
- If you specify a \fBbin\fP directory in \fBdirectories\.bin\fP, all the files in
- that folder will be added\.
- .P
- Because of the way the \fBbin\fP directive works, specifying both a
- \fBbin\fP path and setting \fBdirectories\.bin\fP is an error\. If you want to
- specify individual files, use \fBbin\fP, and for all the files in an
- existing \fBbin\fP directory, use \fBdirectories\.bin\fP\|\.
- .SS directories\.man
- .P
- A folder that is full of man pages\. Sugar to generate a "man" array by
- walking the folder\.
- .SS directories\.doc
- .P
- Put markdown files in here\. Eventually, these will be displayed nicely,
- maybe, someday\.
- .SS directories\.example
- .P
- Put example scripts in here\. Someday, it might be exposed in some clever way\.
- .SS directories\.test
- .P
- Put your tests in here\. It is currently not exposed, but it might be in the
- future\.
- .SH repository
- .P
- Specify the place where your code lives\. This is helpful for people who
- want to contribute\. If the git repo is on GitHub, then the \fBnpm docs\fP
- command will be able to find you\.
- .P
- Do it like this:
- .P
- .RS 2
- .nf
- "repository": {
- "type" : "git",
- "url" : "https://github\.com/npm/cli\.git"
- }
-
- "repository": {
- "type" : "svn",
- "url" : "https://v8\.googlecode\.com/svn/trunk/"
- }
- .fi
- .RE
- .P
- The URL should be a publicly available (perhaps read\-only) url that can be handed
- directly to a VCS program without any modification\. It should not be a url to an
- html project page that you put in your browser\. It's for computers\.
- .P
- For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the same
- shortcut syntax you use for \fBnpm install\fP:
- .P
- .RS 2
- .nf
- "repository": "npm/npm"
-
- "repository": "github:user/repo"
-
- "repository": "gist:11081aaa281"
-
- "repository": "bitbucket:user/repo"
-
- "repository": "gitlab:user/repo"
- .fi
- .RE
- .SH scripts
- .P
- The "scripts" property is a dictionary containing script commands that are run
- at various times in the lifecycle of your package\. The key is the lifecycle
- event, and the value is the command to run at that point\.
- .P
- See npm help 7 \fBnpm\-scripts\fP to find out more about writing package scripts\.
- .SH config
- .P
- A "config" object can be used to set configuration parameters used in package
- scripts that persist across upgrades\. For instance, if a package had the
- following:
- .P
- .RS 2
- .nf
- { "name" : "foo"
- , "config" : { "port" : "8080" } }
- .fi
- .RE
- .P
- and then had a "start" command that then referenced the
- \fBnpm_package_config_port\fP environment variable, then the user could
- override that by doing \fBnpm config set foo:port 8001\fP\|\.
- .P
- See npm help 7 \fBnpm\-config\fP and npm help 7 \fBnpm\-scripts\fP for more on package
- configs\.
- .SH dependencies
- .P
- Dependencies are specified in a simple object that maps a package name to a
- version range\. The version range is a string which has one or more
- space\-separated descriptors\. Dependencies can also be identified with a
- tarball or git URL\.
- .P
- \fBPlease do not put test harnesses or transpilers in your
- \fBdependencies\fP object\.\fR See \fBdevDependencies\fP, below\.
- .P
- See npm help 7 semver for more details about specifying version ranges\.
- .RS 0
- .IP \(bu 2
- \fBversion\fP Must match \fBversion\fP exactly
- .IP \(bu 2
- \fB>version\fP Must be greater than \fBversion\fP
- .IP \(bu 2
- \fB>=version\fP etc
- .IP \(bu 2
- \fB<version\fP
- .IP \(bu 2
- \fB<=version\fP
- .IP \(bu 2
- \fB~version\fP "Approximately equivalent to version" See npm help 7 semver
- .IP \(bu 2
- \fB^version\fP "Compatible with version" See npm help 7 semver
- .IP \(bu 2
- \fB1\.2\.x\fP 1\.2\.0, 1\.2\.1, etc\., but not 1\.3\.0
- .IP \(bu 2
- \fBhttp://\.\.\.\fP See 'URLs as Dependencies' below
- .IP \(bu 2
- \fB*\fP Matches any version
- .IP \(bu 2
- \fB""\fP (just an empty string) Same as \fB*\fP
- .IP \(bu 2
- \fBversion1 \- version2\fP Same as \fB>=version1 <=version2\fP\|\.
- .IP \(bu 2
- \fBrange1 || range2\fP Passes if either range1 or range2 are satisfied\.
- .IP \(bu 2
- \fBgit\.\.\.\fP See 'Git URLs as Dependencies' below
- .IP \(bu 2
- \fBuser/repo\fP See 'GitHub URLs' below
- .IP \(bu 2
- \fBtag\fP A specific version tagged and published as \fBtag\fP See npm help \fBnpm\-dist\-tag\fP
- .IP \(bu 2
- \fBpath/path/path\fP See Local Paths \fI#local\-paths\fR below
-
- .RE
- .P
- For example, these are all valid:
- .P
- .RS 2
- .nf
- { "dependencies" :
- { "foo" : "1\.0\.0 \- 2\.9999\.9999"
- , "bar" : ">=1\.0\.2 <2\.1\.2"
- , "baz" : ">1\.0\.2 <=2\.3\.4"
- , "boo" : "2\.0\.1"
- , "qux" : "<1\.0\.0 || >=2\.3\.1 <2\.4\.5 || >=2\.5\.2 <3\.0\.0"
- , "asd" : "http://asdf\.com/asdf\.tar\.gz"
- , "til" : "~1\.2"
- , "elf" : "~1\.2\.3"
- , "two" : "2\.x"
- , "thr" : "3\.3\.x"
- , "lat" : "latest"
- , "dyl" : "file:\.\./dyl"
- }
- }
- .fi
- .RE
- .SS URLs as Dependencies
- .P
- You may specify a tarball URL in place of a version range\.
- .P
- This tarball will be downloaded and installed locally to your package at
- install time\.
- .SS Git URLs as Dependencies
- .P
- Git urls are of the form:
- .P
- .RS 2
- .nf
- <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit\-ish> | #semver:<semver>]
- .fi
- .RE
- .P
- \fB<protocol>\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, \fBgit+https\fP, or
- \fBgit+file\fP\|\.
- .P
- If \fB#<commit\-ish>\fP is provided, it will be used to clone exactly that
- commit\. If the commit\-ish has the format \fB#semver:<semver>\fP, \fB<semver>\fP 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\. If neither \fB#<commit\-ish>\fP or \fB#semver:<semver>\fP is
- specified, then \fBmaster\fP is used\.
- .P
- Examples:
- .P
- .RS 2
- .nf
- git+ssh://git@github\.com:npm/cli\.git#v1\.0\.27
- git+ssh://git@github\.com:npm/cli#semver:^5\.0
- git+https://isaacs@github\.com/npm/cli\.git
- git://github\.com/npm/cli\.git#v1\.0\.27
- .fi
- .RE
- .SS GitHub URLs
- .P
- As of version 1\.1\.65, you can refer to GitHub urls as just "foo":
- "user/foo\-project"\. Just as with git URLs, a \fBcommit\-ish\fP suffix can be
- included\. For example:
- .P
- .RS 2
- .nf
- {
- "name": "foo",
- "version": "0\.0\.0",
- "dependencies": {
- "express": "expressjs/express",
- "mocha": "mochajs/mocha#4727d357ea",
- "module": "user/repo#feature\\/branch"
- }
- }
- .fi
- .RE
- .SS Local Paths
- .P
- As of version 2\.0\.0 you can provide a path to a local directory that contains a
- package\. Local paths can be saved using \fBnpm install \-S\fP or
- \fBnpm install \-\-save\fP, using any of these forms:
- .P
- .RS 2
- .nf
- \|\.\./foo/bar
- ~/foo/bar
- \|\./foo/bar
- /foo/bar
- .fi
- .RE
- .P
- in which case they will be normalized to a relative path and added to your
- \fBpackage\.json\fP\|\. For example:
- .P
- .RS 2
- .nf
- {
- "name": "baz",
- "dependencies": {
- "bar": "file:\.\./foo/bar"
- }
- }
- .fi
- .RE
- .P
- This 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 packages
- to the public registry\.
- .SH devDependencies
- .P
- If 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\.
- .P
- In this case, it's best to map these additional items in a \fBdevDependencies\fP
- object\.
- .P
- These things will be installed when doing \fBnpm link\fP or \fBnpm install\fP
- from the root of a package, and can be managed like any other npm
- configuration param\. See npm help 7 \fBnpm\-config\fP for more on the topic\.
- .P
- For build steps that are not platform\-specific, such as compiling
- CoffeeScript or other languages to JavaScript, use the \fBprepare\fP
- script to do this, and make the required package a devDependency\.
- .P
- For example:
- .P
- .RS 2
- .nf
- { "name": "ethopia\-waza",
- "description": "a delightfully fruity coffee varietal",
- "version": "1\.2\.3",
- "devDependencies": {
- "coffee\-script": "~1\.6\.3"
- },
- "scripts": {
- "prepare": "coffee \-o lib/ \-c src/waza\.coffee"
- },
- "main": "lib/waza\.js"
- }
- .fi
- .RE
- .P
- The \fBprepare\fP script will be run before publishing, so that users
- can consume the functionality without requiring them to compile it
- themselves\. In dev mode (ie, locally running \fBnpm install\fP), it'll
- run this script as well, so that you can test it easily\.
- .SH peerDependencies
- .P
- In some cases, you want to express the compatibility of your package with a
- host tool or library, while not necessarily doing a \fBrequire\fP of this host\.
- This is usually referred to as a \fIplugin\fR\|\. Notably, your module may be exposing
- a specific interface, expected and specified by the host documentation\.
- .P
- For example:
- .P
- .RS 2
- .nf
- {
- "name": "tea\-latte",
- "version": "1\.3\.5",
- "peerDependencies": {
- "tea": "2\.x"
- }
- }
- .fi
- .RE
- .P
- This ensures your package \fBtea\-latte\fP can be installed \fIalong\fR with the second
- major version of the host package \fBtea\fP only\. \fBnpm install tea\-latte\fP could
- possibly yield the following dependency graph:
- .P
- .RS 2
- .nf
- ├── tea\-latte@1\.3\.5
- └── tea@2\.2\.0
- .fi
- .RE
- .P
- \fBNOTE: npm versions 1 and 2 will automatically install \fBpeerDependencies\fP if
- they are not explicitly depended upon higher in the dependency tree\. In the
- next major version of npm (npm@3), this will no longer be the case\. You will
- receive a warning that the peerDependency is not installed instead\.\fR The
- behavior in npms 1 & 2 was frequently confusing and could easily put you into
- dependency hell, a situation that npm is designed to avoid as much as possible\.
- .P
- Trying to install another plugin with a conflicting requirement will cause an
- error\. For this reason, make sure your plugin requirement is as broad as
- possible, and not to lock it down to specific patch versions\.
- .P
- Assuming the host complies with semver \fIhttps://semver\.org/\fR, only changes in
- the host package's major version will break your plugin\. Thus, if you've worked
- with every 1\.x version of the host package, use \fB"^1\.0"\fP or \fB"1\.x"\fP to express
- this\. If you depend on features introduced in 1\.5\.2, use \fB">= 1\.5\.2 < 2"\fP\|\.
- .SH bundledDependencies
- .P
- This defines an array of package names that will be bundled when publishing
- the package\.
- .P
- In 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 \fBbundledDependencies\fP
- array and executing \fBnpm pack\fP\|\.
- .P
- For example:
- .P
- If we define a package\.json like this:
- .P
- .RS 2
- .nf
- {
- "name": "awesome\-web\-framework",
- "version": "1\.0\.0",
- "bundledDependencies": [
- "renderized", "super\-streams"
- ]
- }
- .fi
- .RE
- .P
- we can obtain \fBawesome\-web\-framework\-1\.0\.0\.tgz\fP file by running \fBnpm pack\fP\|\.
- This file contains the dependencies \fBrenderized\fP and \fBsuper\-streams\fP which
- can be installed in a new project by executing \fBnpm install
- awesome\-web\-framework\-1\.0\.0\.tgz\fP\|\.
- .P
- If this is spelled \fB"bundleDependencies"\fP, then that is also honored\.
- .SH optionalDependencies
- .P
- If 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 \fBoptionalDependencies\fP
- object\. This is a map of package name to version or url, just like the
- \fBdependencies\fP object\. The difference is that build failures do not cause
- installation to fail\.
- .P
- It is still your program's responsibility to handle the lack of the
- dependency\. For example, something like this:
- .P
- .RS 2
- .nf
- try {
- var foo = require('foo')
- var fooVersion = require('foo/package\.json')\.version
- } catch (er) {
- foo = null
- }
- if ( notGoodFooVersion(fooVersion) ) {
- foo = null
- }
-
- // \.\. then later in your program \.\.
-
- if (foo) {
- foo\.doFooThings()
- }
- .fi
- .RE
- .P
- Entries in \fBoptionalDependencies\fP will override entries of the same name in
- \fBdependencies\fP, so it's usually best to only put in one place\.
- .SH engines
- .P
- You can specify the version of node that your stuff works on:
- .P
- .RS 2
- .nf
- { "engines" : { "node" : ">=0\.10\.3 <0\.12" } }
- .fi
- .RE
- .P
- And, like with dependencies, if you don't specify the version (or if you
- specify "*" as the version), then any version of node will do\.
- .P
- If you specify an "engines" field, then npm will require that "node" be
- somewhere on that list\. If "engines" is omitted, then npm will just assume
- that it works on node\.
- .P
- You can also use the "engines" field to specify which versions of npm
- are capable of properly installing your program\. For example:
- .P
- .RS 2
- .nf
- { "engines" : { "npm" : "~1\.0\.20" } }
- .fi
- .RE
- .P
- Unless the user has set the \fBengine\-strict\fP config flag, this
- field is advisory only and will only produce warnings when your package is installed as a dependency\.
- .SH engineStrict
- .P
- \fBThis feature was removed in npm 3\.0\.0\fR
- .P
- Prior to npm 3\.0\.0, this feature was used to treat this package as if the
- user had set \fBengine\-strict\fP\|\. It is no longer used\.
- .SH os
- .P
- You can specify which operating systems your
- module will run on:
- .P
- .RS 2
- .nf
- "os" : [ "darwin", "linux" ]
- .fi
- .RE
- .P
- You can also blacklist instead of whitelist operating systems,
- just prepend the blacklisted os with a '!':
- .P
- .RS 2
- .nf
- "os" : [ "!win32" ]
- .fi
- .RE
- .P
- The host operating system is determined by \fBprocess\.platform\fP
- .P
- It is allowed to both blacklist, and whitelist, although there isn't any
- good reason to do this\.
- .SH cpu
- .P
- If your code only runs on certain cpu architectures,
- you can specify which ones\.
- .P
- .RS 2
- .nf
- "cpu" : [ "x64", "ia32" ]
- .fi
- .RE
- .P
- Like the \fBos\fP option, you can also blacklist architectures:
- .P
- .RS 2
- .nf
- "cpu" : [ "!arm", "!mips" ]
- .fi
- .RE
- .P
- The host architecture is determined by \fBprocess\.arch\fP
- .SH preferGlobal
- .P
- \fBDEPRECATED\fR
- .P
- This option used to trigger an npm warning, but it will no longer warn\. It is
- purely there for informational purposes\. It is now recommended that you install
- any binaries as local devDependencies wherever possible\.
- .SH private
- .P
- If you set \fB"private": true\fP in your package\.json, then npm will refuse
- to publish it\.
- .P
- This is a way to prevent accidental publication of private repositories\. If
- 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
- \fBpublishConfig\fP dictionary described below to override the \fBregistry\fP config
- param at publish\-time\.
- .SH publishConfig
- .P
- This is a set of config values that will be used at publish\-time\. It'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\.
- .P
- Any config values can be overridden, but only "tag", "registry" and "access"
- probably matter for the purposes of publishing\.
- .P
- See npm help 7 \fBnpm\-config\fP to see the list of config options that can be
- overridden\.
- .SH DEFAULT VALUES
- .P
- npm will default some values based on package contents\.
- .RS 0
- .IP \(bu 2
- \fB"scripts": {"start": "node server\.js"}\fP
- If there is a \fBserver\.js\fP file in the root of your package, then npm
- will default the \fBstart\fP command to \fBnode server\.js\fP\|\.
- .IP \(bu 2
- \fB"scripts":{"install": "node\-gyp rebuild"}\fP
- If there is a \fBbinding\.gyp\fP file in the root of your package and you have not defined an \fBinstall\fP or \fBpreinstall\fP script, npm will
- default the \fBinstall\fP command to compile using node\-gyp\.
- .IP \(bu 2
- \fB"contributors": [\.\.\.]\fP
- If there is an \fBAUTHORS\fP file in the root of your package, npm will
- treat each line as a \fBName <email> (url)\fP format, where email and url
- are optional\. Lines which start with a \fB#\fP or are blank, will be
- ignored\.
-
- .RE
- .SH SEE ALSO
- .RS 0
- .IP \(bu 2
- npm help 7 semver
- .IP \(bu 2
- npm help init
- .IP \(bu 2
- npm help version
- .IP \(bu 2
- npm help config
- .IP \(bu 2
- npm help 7 config
- .IP \(bu 2
- npm help help
- .IP \(bu 2
- npm help install
- .IP \(bu 2
- npm help publish
- .IP \(bu 2
- npm help uninstall
-
- .RE
-
|