<h1><ahref="../doc/json.html">json</a></h1><p>Specifics of npm's package.json handling</p>
<h2id="DESCRIPTION">DESCRIPTION</h2>
<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>
<p>A lot of the behavior described in this document is affected by the config
settings described in <code><ahref="../doc/config.html">config(1)</a></code>.</p>
<h2id="DEFAULT-VALUES">DEFAULT VALUES</h2>
<p>npm will default some values based on package contents.</p>
<ul><li><p><code>"scripts": {"start": "node server.js"}</code></p><p>If there is a <code>server.js</code> file in the root of your package, then npm
will default the <code>start</code> command to <code>node server.js</code>.</p></li><li><p><code>"scripts":{"preinstall": "node-waf clean || true; node-waf configure build"}</code></p><p>If there is a <code>wscript</code> file in the root of your package, npm will
default the <code>preinstall</code> command to compile using node-waf.</p></li><li><p><code>"contributors": [...]</code></p><p>If there is an <code>AUTHORS</code> file in the root of your package, npm will
treat each line as a <code>Name <email> (url)</code> format, where email and url
are optional. Lines which start with a <code>#</code> or are blank, will be
ignored.</p></li></ul>
<h2id="name">name</h2>
<p>The <em>most</em> 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>
<p>The name is what your thing is called. Some tips:</p>
<ul><li>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.)</li><li>The name ends up being part of a URL, an argument on the command line, and a
folder name. Any name with non-url-safe characters will be rejected.
Also, it can't start with a dot or an underscore.</li><li>The name will probably be passed as an argument to require(), so it should
be something short, but also reasonably descriptive.</li><li>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. http://registry.npmjs.org/</li></ul>
<h2id="version">version</h2>
<p>The <em>most</em> 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>
<p>Version must be parseable by
<ahref="https://github.com/isaacs/node-semver">node-semver</a>, which is bundled
with npm as a dependency. (<code>npm install semver</code> to use it yourself.)</p>
<p>Here's how npm's semver implementation deviates from what's on semver.org:</p>
<ul><li>Versions can start with "v"</li><li>A numeric item separated from the main three-number version by a hyphen
will be interpreted as a "build" number, and will <em>increase</em> the version.
But, if the tag is not a number separated by a hyphen, then it's treated
as a pre-release tag, and is <em>less than</em> the version without a tag.
So, <code>0.1.2-7 > 0.1.2-7-beta > 0.1.2-6 > 0.1.2 > 0.1.2beta</code></li></ul>
<p>This is a little bit confusing to explain, but matches what you see in practice
when people create tags in git like "v1.2.3" and then do "git describe" to generate
a patch version.</p>
<h2id="description">description</h2>
<p>Put a description in it. It's a string. This helps people discover your
package, as it's listed in <code>npm search</code>.</p>
<h2id="keywords">keywords</h2>
<p>Put keywords in it. It's an array of strings. This helps people
discover your package as it's listed in <code>npm search</code>.</p>
<h2id="homepage">homepage</h2>
<p>The url to the project homepage.</p>
<p><strong>NOTE</strong>: This is <em>not</em> 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>
<p>Literally. Spit. I'm so not kidding.</p>
<h2id="bugs">bugs</h2>
<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
<ul><li><code>version</code> Must match <code>version</code> exactly</li><li><code>=version</code> Same as just <code>version</code></li><li><code>>version</code> Must be greater than <code>version</code></li><li><code>>=version</code> etc</li><li><code><version</code></li><li><code><=version</code></li><li><code>~version</code> See 'Tilde Version Ranges' below</li><li><code>1.2.x</code> See 'X Version Ranges' below</li><li><code>http://...</code> See 'URLs as Dependencies' below</li><li><code>*</code> Matches any version</li><li><code>""</code> (just an empty string) Same as <code>*</code></li><li><code>version1 - version2</code> Same as <code>>=version1 <=version2</code>.</li><li><code>range1 || range2</code> Passes if either range1 or range2 are satisfied.</li><li><code>git...</code> See 'Git URLs as Dependencies' below</li></ul>
