From 71e285b94c7edaa43aa8115965cf5a36b8e0f80a Mon Sep 17 00:00:00 2001 From: Florian Dold Date: Wed, 3 Apr 2019 15:43:32 +0200 Subject: Node.js v11.13.0 --- deps/node/deps/npm/man/man5/package.json.5 | 966 +++++++++++++++++++++++++++++ 1 file changed, 966 insertions(+) create mode 100644 deps/node/deps/npm/man/man5/package.json.5 (limited to 'deps/node/deps/npm/man/man5/package.json.5') diff --git a/deps/node/deps/npm/man/man5/package.json.5 b/deps/node/deps/npm/man/man5/package.json.5 new file mode 100644 index 00000000..dd20f7cb --- /dev/null +++ b/deps/node/deps/npm/man/man5/package.json.5 @@ -0,0 +1,966 @@ +.TH "PACKAGE\.JSON" "5" "January 2019" "" "" +.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 " } +.fi +.RE +.P +Then include a file named \fB\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 (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 \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=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 +://[[:]@][:][:][/][# | #semver:] +.fi +.RE +.P +\fB\fP is one of \fBgit\fP, \fBgit+ssh\fP, \fBgit+http\fP, \fBgit+https\fP, or +\fBgit+file\fP\|\. +.P +If \fB#\fP is provided, it will be used to clone exactly that +commit\. If the commit\-ish has the format \fB#semver:\fP, \fB\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#\fP or \fB#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 (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 + -- cgit v1.2.3