diff options
Diffstat (limited to 'html/doc/json.html')
| -rw-r--r-- | html/doc/json.html | 768 |
1 files changed, 768 insertions, 0 deletions
diff --git a/html/doc/json.html b/html/doc/json.html new file mode 100644 index 000000000..6d5651856 --- /dev/null +++ b/html/doc/json.html @@ -0,0 +1,768 @@ +<!doctype html> +<html> + <title>npm-json</title> +<style type="text/css"> + +/* reset */ +* { + margin:0; + padding:0; + border:none; + font-family:inherit; + font-size:inherit; + font-weight:inherit; +} +:target::before { + content:" → "; + position:absolute; + display:block; + opacity:0.5; + color:#f00; + margin:0 0 0 -1.2em; +} +abbr, acronym { + border-bottom:1px dotted #aaa; +} +kbd, code, pre { + font-family:monospace; + margin:0; + font-size:18px; + line-height:24px; + background:#eee; + outline:1px solid #ccc; +} +kbd code, kbd pre, kbd kbd, +pre code, pre pre, pre kbd, +code code, code pre, code kbd { outline: none } +.dollar::before { + content:"$ "; + display:inline; +} +p, ul, ol, dl, pre { + margin:30px 0; + line-height:30px; +} +hr { + margin:30px auto 29px; + width:66%; + height:1px; + background:#aaa; +} +pre { + display:block; +} +dd :first-child { + margin-top:0; +} + +body { + quotes:"“" "”" "‘" "’"; + width:666px; + margin:30px auto 120px; + font-family:Times New Roman, serif; + font-size:20px; + background:#fff; + line-height:30px; + color:#111; +} + +blockquote { + position:relative; + font-size:16px; + line-height:30px; + font-weight:bold; + width:85%; + margin:0 auto; +} +blockquote::before { + font-size:90px; + display:block; + position:absolute; + top:20px; + right:100%; + content:"“"; + padding-right:10px; + color:#ccc; +} +.source cite::before { + content:"— "; +} +.source { + padding-left:20%; + margin-top:30px; +} +.source cite span { + font-style:normal; +} +blockquote p { + margin-bottom:0; +} +.quote blockquote { + font-weight:normal; +} + +h1, h2, h3, h4, h5, h6, dt, #header { + font-family:serif; + font-size:20px; + font-weight:bold; +} +h2 { + background:#eee; +} +h1, h2 { + line-height:40px; +} + +i, em, cite { + font-style:italic; +} +b, strong { + font-weight:bold; +} +i, em, cite, b, strong, small { + line-height:28px; +} +small, .small, .small *, aside { + font-style:italic; + color:#669; + font-size:18px; +} +spall a, .small a { + text-decoration:underline; +} +del { + text-decoration:line-through; +} +ins { + text-decoration:underline; +} +.alignright { display:block; float:right; margin-left:1em; } +.alignleft { display:block; float:left; margin-right:1em; } + +q:before, q q q:before, q q q q q:before, q q q q q q q:before { content:"“"; } +q q:before, q q q q:before, q q q q q q:before, q q q q q q q q:before { content:"‘"; } +q:after, q q q:after, q q q q q:after, q q q q q q q:after { content:"”"; } +q q:after, q q q q:after, q q q q q q:after, q q q q q q q q:after { content:"’"; } + +a { color:#00f; text-decoration:none; } +a:visited { color:#636; } +a:hover, a:active { color:#900!important; text-decoration:underline; } + +h1 { + font-weight:bold; + background:#fff; +} + +.navigation { + display:table; + width:100%; + margin:0 0 30px 0; + position:relative; +} +#nav-above { + margin-bottom:0; +} +.navigation .nav-previous { + display:table-cell; + text-align:left; + width:50%; +} +/* hang the » and « off into the margins */ +.navigation .nav-previous a:before, .navigation .nav-next a:after { + content: "«"; + display:block; + height:30px; + margin-bottom:-30px; + text-decoration:none; + margin-left:-15px; +} +.navigation .nav-next a:after { + content: "»"; + text-align:right; + margin-left:0; + margin-top:-30px; + margin-right:-15px; +} + + +.navigation .nav-next { + display:table-cell; + text-align:right; + width:50%; +} +.navigation a { + display:block; + width:100%; + height:100%; +} + +input, button, textarea { + border:0; + line-height:30px; +} +textarea { + height:300px; +} +input { + height:30px; + line-height:30px; +} +input.submit, input#submit, input.button, button, input[type=submit] { + cursor:hand; cursor:pointer; + outline:1px solid #ccc; +} + +#wrapper { + margin-bottom:90px; + position:relative; + z-index:1; + *zoom:1; + background:#fff; +} +#wrapper:after { + display:block; + content:"."; + visibility:hidden; + width:0; + height:0; + clear:both; +} + +.sidebar .xoxo > li { + float:left; + width:50%; +} +.sidebar li { + list-style:none; +} +.sidebar #elsewhere { + margin-left:-10%; + margin-right:-10%; +} +.sidebar #rss-links, .sidebar #twitter-feeds { + float:right; + clear:right; + width:20%; +} +.sidebar #comment { + clear:both; + float:none; + width:100%; +} +.sidebar #search { + clear:both; + float:none; + width:100%; +} +.sidebar #search h2 { + margin-left:40%; +} +.sidebar #search #s { + width:90%; + float:left; +} +.sidebar #search #searchsubmit { + width:10%; + float:right; +} +.sidebar * { + font-size:15px; + line-height:30px; +} + +#footer, #footer * { + margin:300px 0 0; + text-align:right; + font-size:14px; + line-height:90px; +} + +#toc { + position:absolute; + top:0; + right:0; + padding:40px 0 40px 20px; + margin:0; + width:200px; + opacity:0.2; + z-index:-1; +} +#toc:hover { + opacity:1; + background:#fff; + z-index:999; +} +#toc ul { + padding:0; + margin:0; +} +#toc, #toc li { + list-style-type:none; + font-size:15px; + line-height:15px; +} +#toc li { + padding:0 0 0 10px; +} + + +@media print { + a[href] { + color:inherit; + } + a[href]:after { + white-space:nowrap; + content:" " attr(href); + } + a[href^=\#], .navigation { + display:none; + } +} +</style> + + <body> + <div id="wrapper"> +<h1><a href="json.html">npm-json(1)</a> -- Specifics of npm's package.json handling</h1> + +<h2 id="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>npm help config</code>.</p> + +<h2 id="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> + +<h2 id="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> + +<h2 id="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 +<a href="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> + +<h2 id="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> + +<h2 id="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> + +<h2 id="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> + +<h2 id="people-fields-author-contributors">people fields: author, contributors</h2> + +<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> + +<pre><code>{ "name" : "Barney Rubble" +, "email" : "b@rubble.com" +, "url" : "http://barnyrubble.tumblr.com/" +}</code></pre> + +<p>Or you can shorten that all into a single string, and npm will parse it for you:</p> + +<pre><code>"Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)</code></pre> + +<p>Both email and url are optional either way.</p> + +<p>npm also sets a top-level "maintainers" field with your npm user info.</p> + +<h2 id="files">files</h2> + +<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> + +<p>You can also provide a ".npmignore" file in the root of your package, +which will keep files from being included, even if they would be picked +up by the files array. The ".npmignore" file works just like a +".gitignore".</p> + +<h2 id="main">main</h2> + +<p>The main field is a module ID that is the primary entry point to your program. +That is, if your package is named <code>foo</code>, and a user installs it, and then does +<code>require("foo")</code>, then your main module's exports object will be returned.</p> + +<p>This should be a module ID relative to the root of your package folder.</p> + +<p>For most modules, it makes the most sense to have a main script and often not +much else.</p> + +<h2 id="bin">bin</h2> + +<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> + +<p>To use this, supply a <code>bin</code> field in your package.json which is a map of +command name to local file name. On install, npm will link that file into +place right next to wherever node is installed. (Presumably, this is in your +PATH, and defaults to <code>/usr/local/bin</code>.) On activation, the versioned file +will get linked to the main filename (just like how the main.js stuff works, +but with an executable in the PATH.)</p> + +<p>For example, npm has this:</p> + +<pre><code>{ "bin" : { "npm" : "./cli.js" } }</code></pre> + +<p>So, when you install npm, it'll create a symlink from the <code>cli.js</code> script to +<code>/usr/local/bin/npm-version</code>. Then, when you activate that version, it'll +create a symlink from <code>/usr/local/bin/npm-version</code> to <code>/usr/local/bin/npm</code>.</p> + +<p>Notice that if the executable file is interpreted by node (i.e., specifying +node in the shebang line), npm actually installs a shim instead of symlinking +it, which causes expressions <code>require.main === module</code> and <code>module.id === "."</code> +evaluate to <code>false</code> within the file. This seems unable to be resolved until +node provides a "flexible <code>require()</code>".</p> + +<p>Shortcut: If you have a single executable, and its name is already what you +want it to be, then you can just supply it as a string. For example:</p> + +<pre><code>{ "bin" : "./path/to/program" }</code></pre> + +<p>would be the same as this:</p> + +<pre><code>{ "bin" : { "program" : "./path/to/program" } }</code></pre> + +<h2 id="man">man</h2> + +<p>Specify either a single file or an array of filenames to put in place for the +<code>man</code> program to find.</p> + +<p>If only a single file is provided, then it's installed such that it is the +result from <code>man <pkgname></code>, regardless of its actual filename. For example:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : "./man/doc.1" +}</code></pre> + +<p>would link the <code>./man/doc.1</code> file in such that it is the target for <code>man foo</code></p> + +<p>If the filename doesn't start with the package name, then it's prefixed. +So, this:</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/bar.1" ] +}</code></pre> + +<p>will create files to do <code>man foo</code> and <code>man foo-bar</code>.</p> + +<p>Man files must end with a number, and optionally a <code>.gz</code> suffix if they are +compressed. The number dictates which man section the file is installed into.</p> + +<pre><code>{ "name" : "foo" +, "version" : "1.2.3" +, "description" : "A packaged foo fooer for fooing foos" +, "main" : "foo.js" +, "man" : [ "./man/foo.1", "./man/foo.2" ] +}</code></pre> + +<p>will create entries for <code>man foo</code> and <code>man 2 foo</code></p> + +<h2 id="directories">directories</h2> + +<p>The CommonJS <a href="http://wiki.commonjs.org/wiki/Packages/1.0">Packages</a> spec details a +few ways that you can indicate the structure of your package using a <code>directories</code> +hash. If you look at <a href="http://registry.npmjs.org/npm/latest">npm's package.json</a>, +you'll see that it has directories for doc, lib, and man.</p> + +<p>In the future, this information may be used in other creative ways.</p> + +<h3 id="directories-lib">directories.lib</h3> + +<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.</p> + +<h3 id="directories-bin">directories.bin</h3> + +<p>If you specify a "bin" directory, then all the files in that folder will +be used as the "bin" hash.</p> + +<p>If you have a "bin" hash already, then this has no effect.</p> + +<h3 id="directories-man">directories.man</h3> + +<p>A folder that is full of man pages. Sugar to generate a "man" array by +walking the folder.</p> + +<h3 id="directories-doc">directories.doc</h3> + +<p>Put markdown files in here. Eventually, these will be displayed nicely, +maybe, someday.</p> + +<h3 id="directories-example">directories.example</h3> + +<p>Put example scripts in here. Someday, it might be exposed in some clever way.</p> + +<h2 id="repository">repository</h2> + +<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 <code>npm docs</code> +command will be able to find you.</p> + +<p>Do it like this:</p> + +<pre><code>"repository" : + { "type" : "git" + , "url" : "http://github.com/isaacs/npm.git" + } + +"repository" : + { "type" : "svn" + , "url" : "http://v8.googlecode.com/svn/trunk/" + }</code></pre> + +<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> + +<h2 id="scripts">scripts</h2> + +<p>The "scripts" member is an object hash of 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> + +<p>See <code>npm help scripts</code> to find out more about writing package scripts.</p> + +<h2 id="config">config</h2> + +<p>A "config" hash can be used to set configuration +parameters used in package scripts that persist across upgrades. For +instance, if a package had the following:</p> + +<pre><code>{ "name" : "foo" +, "config" : { "port" : "8080" } }</code></pre> + +<p>and then had a "start" command that then referenced the +<code>npm_package_config_port</code> environment variable, then the user could +override that by doing <code>npm config set foo:port 8001</code>.</p> + +<p>See <code>npm help config</code> and <code>npm help scripts</code> for more on package +configs.</p> + +<h2 id="dependencies">dependencies</h2> + +<p>Dependencies are specified with a simple hash of package name to version +range. The version range is EITHER a string which has one or more +space-separated descriptors, OR a range like "fromVersion - toVersion"</p> + +<p><strong>Please do not put test harnesses in your <code>dependencies</code> hash.</strong> See +<code>devDependencies</code>, below.</p> + +<p>Version range descriptors may be any of the following styles, where "version" +is a semver compatible version identifier.</p> + +<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></ul> + +<p>For example, these are all valid:</p> + +<pre><code>{ "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" + } +}</code></pre> + +<h3 id="Tilde-Version-Ranges">Tilde Version Ranges</h3> + +<p>A range specifier starting with a tilde <code>~</code> character is matched against +a version in the following fashion.</p> + +<ul><li>The version must be at least as high as the range.</li><li>The version must be less than the next major revision above the range.</li></ul> + +<p>For example, the following are equivalent:</p> + +<ul><li><code>"~1.2.3" = ">=1.2.3 <1.3.0"</code></li><li><code>"~1.2" = ">=1.2.0 <2.0.0"</code></li><li><code>"~1" = ">=1.0.0 <2.0.0"</code></li></ul> + +<h3 id="X-Version-Ranges">X Version Ranges</h3> + +<p>An "x" in a version range specifies that the version number must start +with the supplied digits, but any digit may be used in place of the x.</p> + +<p>The following are equivalent:</p> + +<ul><li><code>"1.2.x" = ">=1.2.0 <1.3.0"</code></li><li><code>"1.x.x" = ">=1.0.0 <2.0.0"</code></li><li><code>"1.2" = "1.2.x"</code></li><li><code>"1.x" = "1.x.x"</code></li><li><code>"1" = "1.x.x"</code></li></ul> + +<p>You may not supply a comparator with a version containing an x. Any +digits after the first "x" are ignored.</p> + +<h3 id="URLs-as-Dependencies">URLs as Dependencies</h3> + +<p>Starting with npm version 0.2.14, you may specify a tarball URL in place +of a version range.</p> + +<p>This tarball will be downloaded and installed locally to your package at +install time.</p> + +<h2 id="devDependencies">devDependencies</h2> + +<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> + +<p>In this case, it's best to list these additional items in a +<code>devDependencies</code> hash.</p> + +<p>These things will be installed whenever the <code>--dev</code> configuration flag +is set. This flag is set automatically when doing <code>npm link</code>, and can +be managed like any other npm configuration param. See <code>npm help +config</code> for more on the topic.</p> + +<h2 id="bundledDependencies">bundledDependencies</h2> + +<p>Array of package names that will be bundled when publishing the package.</p> + +<h2 id="engines">engines</h2> + +<p>Packages/1.0 says that you can have an "engines" field with an array of engine +names. However, it has no provision for specifying which version of the engine +your stuff runs on.</p> + +<p>With npm, you can use either of the following styles to specify the version of +node that your stuff works on:</p> + +<pre><code>{ "engines" : [ "node >=0.1.27 <0.1.30" ] }</code></pre> + +<p>or:</p> + +<pre><code>{ "engines" : { "node" : ">=0.1.27 <0.1.30" } }</code></pre> + +<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> + +<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> + +<h2 id="preferGlobal">preferGlobal</h2> + +<p>If your package is primarily a command-line application that should be +installed globally, then set this value to <code>true</code> to provide a warning +if it is installed locally.</p> + +<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.</p> + +<h2 id="private">private</h2> + +<p>If you set <code>"private": true</code> in your package.json, then npm will refuse +to publish it.</p> + +<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 speciic registry (for example, an internal registry), +then use the <code>publishConfig</code> hash described below +to override the <code>registry</code> config param at publish-time.</p> + +<h2 id="publishConfig">publishConfig</h2> + +<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 or registry, so that you can +ensure that a given package is not tagged with "latest" or published to +the global public registry by default.</p> + +<p>Any config values can be overridden, but of course only "tag" and +"registry" probably matter for the purposes of publishing.</p> + +<p>See <code>npm help config</code> to see the list of config options that can be +overridden.</p> +</div> +<script> +els = Array.prototype.slice.call((wrapper = document.getElementById("wrapper")) +.getElementsByTagName("*"), 0) +.filter(function (el) { + return el.parentNode === wrapper + && el.tagName.match(/H[1-6]/) + && el.id +}) +var l = 2 +;(toc = document.createElement("ul")).innerHTML = els.map(function (el) { + var i = el.tagName.charAt(1) + , out = "" + while (i > l) { + out += "<ul>" + l ++ + } + while (i < l) { + out += "</ul>" + l -- + } + out += "<li><a href='#" + el.id + "'>" + el.innerHTML + "</a>" + return out +}).join("\n") +toc.id = "toc" +document.body.appendChild(toc) + +</script> +</body></html> +<!-- npm help json - 2011-31-04 05:09:22 --> |