| .TH "PACKAGE\.JSON" "5" "June 2016" "" "" |
| .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 |
| The \fImost\fR important things in your package\.json are the name and version fields\. |
| Those are actually required, and your package won't install without |
| them\. 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\. |
| .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 |
| The \fImost\fR important things in your package\.json are the name and version fields\. |
| Those are actually required, and your package won't install without |
| them\. 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\. |
| .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 |
| \fBNOTE\fR: This is \fInot\fR the same as "url"\. If you put a "url" field, |
| then the registry will think it's a redirection to your package that has |
| been published somewhere else, and spit at you\. |
| .P |
| Literally\. Spit\. I'm so not kidding\. |
| .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://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" : "http://opensource\.org/licenses/ISC" |
| } |
| } |
| |
| // Not valid metadata |
| { "licenses" : |
| [ |
| { "type": "MIT" |
| , "url": "http://www\.opensource\.org/licenses/mit\-license\.php" |
| } |
| , { "type": "Apache\-2\.0" |
| , "url": "http://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 "files" field is an array of files to include in your project\. If |
| you name a folder in the array, then it will also include the files |
| inside that folder\. (Unless they would be ignored by another rule\.) |
| .P |
| You can also provide a "\.npmignore" file in the root of your package or |
| in subdirectories, which will keep files from being included, even |
| if they would be picked up by the files array\. The \fB\|\.npmignore\fP file |
| works just like a \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 (any casing and file extension) |
| .IP \(bu 2 |
| \fBLICENSE\fP / \fBLICENCE\fP |
| .IP \(bu 2 |
| The file in the "main" field |
| |
| .RE |
| .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 |
| |
| .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 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 |
| .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/npm\.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": "gist:11081aaa281" |
| |
| "repository": "bitbucket:example/repo" |
| |
| "repository": "gitlab:another/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\-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 can be of the form: |
| .P |
| .RS 2 |
| .nf |
| git://github\.com/user/project\.git#commit\-ish |
| git+ssh://user@hostname:project\.git#commit\-ish |
| git+ssh://user@hostname/project\.git#commit\-ish |
| git+http://user@hostname/project/blah\.git#commit\-ish |
| git+https://user@hostname/project/blah\.git#commit\-ish |
| .fi |
| .RE |
| .P |
| The \fBcommit\-ish\fP can be any tag, sha, or branch which can be supplied as |
| an argument to \fBgit checkout\fP\|\. The default is \fBmaster\fP\|\. |
| .SH 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": "visionmedia/express", |
| "mocha": "visionmedia/mocha#4727d357ea" |
| } |
| } |
| .fi |
| .RE |
| .SH 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 \-\-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 \fBprepublish\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": { |
| "prepublish": "coffee \-o lib/ \-c src/waza\.coffee" |
| }, |
| "main": "lib/waza\.js" |
| } |
| .fi |
| .RE |
| .P |
| The \fBprepublish\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 \fIhttp://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: |
| 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 will produce warnings when your package is installed as a dependency\. |
| .SH engineStrict |
| .P |
| \fBNOTE: This feature is deprecated and will be removed in npm 3\.0\.0\.\fR |
| .P |
| If you are sure that your module will \fIdefinitely not\fR run properly on |
| versions of Node/npm other than those specified in the \fBengines\fP object, |
| then you can set \fB"engineStrict": true\fP in your package\.json file\. |
| This will override the user's \fBengine\-strict\fP config setting\. |
| .P |
| Please do not do this unless you are really very very sure\. If your |
| engines object is something overly restrictive, you can quite easily and |
| inadvertently lock yourself into obscurity and prevent your users from |
| updating to new versions of Node\. Consider this choice carefully\. |
| .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 |
| If your package is primarily a command\-line application that should be |
| installed globally, then set this value to \fBtrue\fP to provide a warning |
| if it is installed locally\. |
| .P |
| It doesn't actually prevent users from installing it locally, but it |
| does help prevent some confusion if it doesn't work as expected\. |
| .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 of course 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 7 faq |
| .IP \(bu 2 |
| npm help install |
| .IP \(bu 2 |
| npm help publish |
| .IP \(bu 2 |
| npm help uninstall |
| |
| .RE |
| |