deps/npm/html/doc/misc/npm-faq.html

   1 <!doctype html>
   2 <html>
   3   <title>npm-faq</title>
   4   <meta http-equiv="content-type" value="text/html;utf-8">
   5   <link rel="stylesheet" type="text/css" href="../../static/style.css">
   6
   7   <body>
   8     <div id="wrapper">
   9 <h1><a href="../misc/npm-faq.html">npm-faq</a></h1> <p>Frequently Asked Questions</p>
  10
  11 <h2 id="Where-can-I-find-these-docs-in-HTML">Where can I find these docs in HTML?</h2>
  12
  13 <p><a href="https://npmjs.org/doc/">https://npmjs.org/doc/</a>, or run:</p>
  14
  15 <pre><code>npm config set viewer browser</code></pre>
  16
  17 <p>to open these documents in your default web browser rather than <code>man</code>.</p>
  18
  19 <h2 id="It-didn-t-work">It didn&#39;t work.</h2>
  20
  21 <p>That&#39;s not really a question.</p>
  22
  23 <h2 id="Why-didn-t-it-work">Why didn&#39;t it work?</h2>
  24
  25 <p>I don&#39;t know yet.</p>
  26
  27 <p>Read the error output, and if you can&#39;t figure out what it means,
  28 do what it says and post a bug with all the information it asks for.</p>
  29
  30 <h2 id="Where-does-npm-put-stuff">Where does npm put stuff?</h2>
  31
  32 <p>See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code></p>
  33
  34 <p>tl;dr:</p>
  35
  36 <ul><li>Use the <code>npm root</code> command to see where modules go, and the <code>npm bin</code>
  37 command to see where executables go</li><li>Global installs are different from local installs.  If you install
  38 something with the <code>-g</code> flag, then its executables go in <code>npm bin -g</code>
  39 and its modules go in <code>npm root -g</code>.</li></ul>
  40
  41 <h2 id="How-do-I-install-something-on-my-computer-in-a-central-location">How do I install something on my computer in a central location?</h2>
  42
  43 <p>Install it globally by tacking <code>-g</code> or <code>--global</code> to the command.  (This
  44 is especially important for command line utilities that need to add
  45 their bins to the global system <code>PATH</code>.)</p>
  46
  47 <h2 id="I-installed-something-globally-but-I-can-t-require-it">I installed something globally, but I can&#39;t <code>require()</code> it</h2>
  48
  49 <p>Install it locally.</p>
  50
  51 <p>The global install location is a place for command-line utilities
  52 to put their bins in the system <code>PATH</code>.  It&#39;s not for use with <code>require()</code>.</p>
  53
  54 <p>If you <code>require()</code> a module in your code, then that means it&#39;s a
  55 dependency, and a part of your program.  You need to install it locally
  56 in your program.</p>
  57
  58 <h2 id="Why-can-t-npm-just-put-everything-in-one-place-like-other-package-managers">Why can&#39;t npm just put everything in one place, like other package managers?</h2>
  59
  60 <p>Not every change is an improvement, but every improvement is a change.
  61 This would be like asking git to do network IO for every commit.  It&#39;s
  62 not going to happen, because it&#39;s a terrible idea that causes more
  63 problems than it solves.</p>
  64
  65 <p>It is much harder to avoid dependency conflicts without nesting
  66 dependencies.  This is fundamental to the way that npm works, and has
  67 proven to be an extremely successful approach.  See <code><a href="../files/npm-folders.html">npm-folders(5)</a></code> for
  68 more details.</p>
  69
  70 <p>If you want a package to be installed in one place, and have all your
  71 programs reference the same copy of it, then use the <code>npm link</code> command.
  72 That&#39;s what it&#39;s for.  Install it globally, then link it into each
  73 program that uses it.</p>
  74
  75 <h2 id="Whatever-I-really-want-the-old-style-everything-global-style">Whatever, I really want the old style &#39;everything global&#39; style.</h2>
  76
  77 <p>Write your own package manager, then.  It&#39;s not that hard.</p>
  78
  79 <p>npm will not help you do something that is known to be a bad idea.</p>
  80
  81 <h2 id="Should-I-check-my-node_modules-folder-into-git">Should I check my <code>node_modules</code> folder into git?</h2>
  82
  83 <p>Mikeal Rogers answered this question very well:</p>
  84
  85 <p><a href="http://www.mikealrogers.com/posts/nodemodules-in-git.html">http://www.mikealrogers.com/posts/nodemodules-in-git.html</a></p>
  86
  87 <p>tl;dr</p>
  88
  89 <ul><li>Check <code>node_modules</code> into git for things you <strong>deploy</strong>, such as
  90 websites and apps.</li><li>Do not check <code>node_modules</code> into git for libraries and modules
  91 intended to be reused.</li><li>Use npm to manage dependencies in your dev environment, but not in
  92 your deployment scripts.</li></ul>
  93
  94 <h2 id="Is-it-npm-or-NPM-or-Npm">Is it &#39;npm&#39; or &#39;NPM&#39; or &#39;Npm&#39;?</h2>
  95
  96 <p>npm should never be capitalized unless it is being displayed in a
  97 location that is customarily all-caps (such as the title of man pages.)</p>
  98
  99 <h2 id="If-npm-is-an-acronym-why-is-it-never-capitalized">If &#39;npm&#39; is an acronym, why is it never capitalized?</h2>
 100
 101 <p>Contrary to the belief of many, &quot;npm&quot; is not in fact an abbreviation for
 102 &quot;Node Package Manager&quot;.  It is a recursive bacronymic abbreviation for
 103 &quot;npm is not an acronym&quot;.  (If it was &quot;ninaa&quot;, then it would be an
 104 acronym, and thus incorrectly named.)</p>
 105
 106 <p>&quot;NPM&quot;, however, <em>is</em> an acronym (more precisely, a capitonym) for the
 107 National Association of Pastoral Musicians.  You can learn more
 108 about them at <a href="http://npm.org/">http://npm.org/</a>.</p>
 109
 110 <p>In software, &quot;NPM&quot; is a Non-Parametric Mapping utility written by
 111 Chris Rorden.  You can analyze pictures of brains with it.  Learn more
 112 about the (capitalized) NPM program at <a href="http://www.cabiatl.com/mricro/npm/">http://www.cabiatl.com/mricro/npm/</a>.</p>
 113
 114 <p>The first seed that eventually grew into this flower was a bash utility
 115 named &quot;pm&quot;, which was a shortened descendent of &quot;pkgmakeinst&quot;, a
 116 bash function that was used to install various different things on different
 117 platforms, most often using Yahoo&#39;s <code>yinst</code>.  If <code>npm</code> was ever an
 118 acronym for anything, it was <code>node pm</code> or maybe <code>new pm</code>.</p>
 119
 120 <p>So, in all seriousness, the &quot;npm&quot; project is named after its command-line
 121 utility, which was organically selected to be easily typed by a right-handed
 122 programmer using a US QWERTY keyboard layout, ending with the
 123 right-ring-finger in a postition to type the <code>-</code> key for flags and
 124 other command-line arguments.  That command-line utility is always
 125 lower-case, though it starts most sentences it is a part of.</p>
 126
 127 <h2 id="How-do-I-list-installed-packages">How do I list installed packages?</h2>
 128
 129 <p><code>npm ls</code></p>
 130
 131 <h2 id="How-do-I-search-for-packages">How do I search for packages?</h2>
 132
 133 <p><code>npm search</code></p>
 134
 135 <p>Arguments are greps.  <code>npm search jsdom</code> shows jsdom packages.</p>
 136
 137 <h2 id="How-do-I-update-npm">How do I update npm?</h2>
 138
 139 <pre><code>npm update npm -g</code></pre>
 140
 141 <p>You can also update all outdated local packages by doing <code>npm update</code> without
 142 any arguments, or global packages by doing <code>npm update -g</code>.</p>
 143
 144 <p>Occasionally, the version of npm will progress such that the current
 145 version cannot be properly installed with the version that you have
 146 installed already.  (Consider, if there is ever a bug in the <code>update</code>
 147 command.)</p>
 148
 149 <p>In those cases, you can do this:</p>
 150
 151 <pre><code>curl https://npmjs.org/install.sh | sh</code></pre>
 152
 153 <h2 id="What-is-a-package">What is a <code>package</code>?</h2>
 154
 155 <p>A package is:</p>
 156
 157 <ul><li>a) a folder containing a program described by a package.json file</li><li>b) a gzipped tarball containing (a)</li><li>c) a url that resolves to (b)</li><li>d) a <code>&lt;name&gt;@&lt;version&gt;</code> that is published on the registry with (c)</li><li>e) a <code>&lt;name&gt;@&lt;tag&gt;</code> that points to (d)</li><li>f) a <code>&lt;name&gt;</code> that has a &quot;latest&quot; tag satisfying (e)</li><li>g) a <code>git</code> url that, when cloned, results in (a).</li></ul>
 158
 159 <p>Even if you never publish your package, you can still get a lot of
 160 benefits of using npm if you just want to write a node program (a), and
 161 perhaps if you also want to be able to easily install it elsewhere
 162 after packing it up into a tarball (b).</p>
 163
 164 <p>Git urls can be of the form:</p>
 165
 166 <pre><code>git://github.com/user/project.git#commit-ish
 167 git+ssh://user@hostname:project.git#commit-ish
 168 git+http://user@hostname/project/blah.git#commit-ish
 169 git+https://user@hostname/project/blah.git#commit-ish</code></pre>
 170
 171 <p>The <code>commit-ish</code> can be any tag, sha, or branch which can be supplied as
 172 an argument to <code>git checkout</code>.  The default is <code>master</code>.</p>
 173
 174 <h2 id="What-is-a-module">What is a <code>module</code>?</h2>
 175
 176 <p>A module is anything that can be loaded with <code>require()</code> in a Node.js
 177 program.  The following things are all examples of things that can be
 178 loaded as modules:</p>
 179
 180 <ul><li>A folder with a <code>package.json</code> file containing a <code>main</code> field.</li><li>A folder with an <code>index.js</code> file in it.</li><li>A JavaScript file.</li></ul>
 181
 182 <p>Most npm packages are modules, because they are libraries that you
 183 load with <code>require</code>.  However, there&#39;s no requirement that an npm
 184 package be a module!  Some only contain an executable command-line
 185 interface, and don&#39;t provide a <code>main</code> field for use in Node programs.</p>
 186
 187 <p>Almost all npm packages (at least, those that are Node programs)
 188 <em>contain</em> many modules within them (because every file they load with
 189 <code>require()</code> is a module).</p>
 190
 191 <p>In the context of a Node program, the <code>module</code> is also the thing that
 192 was loaded <em>from</em> a file.  For example, in the following program:</p>
 193
 194 <pre><code>var req = require(&#39;request&#39;)</code></pre>
 195
 196 <p>we might say that &quot;The variable <code>req</code> refers to the <code>request</code> module&quot;.</p>
 197
 198 <h2 id="So-why-is-it-the-node_modules-folder-but-package-json-file-Why-not-node_packages-or-module-json">So, why is it the &quot;<code>node_modules</code>&quot; folder, but &quot;<code>package.json</code>&quot; file?  Why not <code>node_packages</code> or <code>module.json</code>?</h2>
 199
 200 <p>The <code>package.json</code> file defines the package.  (See &quot;What is a
 201 package?&quot; above.)</p>
 202
 203 <p>The <code>node_modules</code> folder is the place Node.js looks for modules.
 204 (See &quot;What is a module?&quot; above.)</p>
 205
 206 <p>For example, if you create a file at <code>node_modules/foo.js</code> and then
 207 had a program that did <code>var f = require(&#39;foo.js&#39;)</code> then it would load
 208 the module.  However, <code>foo.js</code> is not a &quot;package&quot; in this case,
 209 because it does not have a package.json.</p>
 210
 211 <p>Alternatively, if you create a package which does not have an
 212 <code>index.js</code> or a <code>&quot;main&quot;</code> field in the <code>package.json</code> file, then it is
 213 not a module.  Even if it&#39;s installed in <code>node_modules</code>, it can&#39;t be
 214 an argument to <code>require()</code>.</p>
 215
 216 <h2 id="node_modules-is-the-name-of-my-deity-s-arch-rival-and-a-Forbidden-Word-in-my-religion-Can-I-configure-npm-to-use-a-different-folder"><code>&quot;node_modules&quot;</code> is the name of my deity&#39;s arch-rival, and a Forbidden Word in my religion.  Can I configure npm to use a different folder?</h2>
 217
 218 <p>No.  This will never happen.  This question comes up sometimes,
 219 because it seems silly from the outside that npm couldn&#39;t just be
 220 configured to put stuff somewhere else, and then npm could load them
 221 from there.  It&#39;s an arbitrary spelling choice, right?  What&#39;s the big
 222 deal?</p>
 223
 224 <p>At the time of this writing, the string <code>&#39;node_modules&#39;</code> appears 151
 225 times in 53 separate files in npm and node core (excluding tests and
 226 documentation).</p>
 227
 228 <p>Some of these references are in node&#39;s built-in module loader.  Since
 229 npm is not involved <strong>at all</strong> at run-time, node itself would have to
 230 be configured to know where you&#39;ve decided to stick stuff.  Complexity
 231 hurdle #1.  Since the Node module system is locked, this cannot be
 232 changed, and is enough to kill this request.  But I&#39;ll continue, in
 233 deference to your deity&#39;s delicate feelings regarding spelling.</p>
 234
 235 <p>Many of the others are in dependencies that npm uses, which are not
 236 necessarily tightly coupled to npm (in the sense that they do not read
 237 npm&#39;s configuration files, etc.)  Each of these would have to be
 238 configured to take the name of the <code>node_modules</code> folder as a
 239 parameter.  Complexity hurdle #2.</p>
 240
 241 <p>Furthermore, npm has the ability to &quot;bundle&quot; dependencies by adding
 242 the dep names to the <code>&quot;bundledDependencies&quot;</code> list in package.json,
 243 which causes the folder to be included in the package tarball.  What
 244 if the author of a module bundles its dependencies, and they use a
 245 different spelling for <code>node_modules</code>?  npm would have to rename the
 246 folder at publish time, and then be smart enough to unpack it using
 247 your locally configured name.  Complexity hurdle #3.</p>
 248
 249 <p>Furthermore, what happens when you <em>change</em> this name?  Fine, it&#39;s
 250 easy enough the first time, just rename the <code>node_modules</code> folders to
 251 <code>./blergyblerp/</code> or whatever name you choose.  But what about when you
 252 change it again?  npm doesn&#39;t currently track any state about past
 253 configuration settings, so this would be rather difficult to do
 254 properly.  It would have to track every previous value for this
 255 config, and always accept any of them, or else yesterday&#39;s install may
 256 be broken tomorrow.  Complexity hurdle #5.</p>
 257
 258 <p>Never going to happen.  The folder is named <code>node_modules</code>.  It is
 259 written indelibly in the Node Way, handed down from the ancient times
 260 of Node 0.3.</p>
 261
 262 <h2 id="How-do-I-install-node-with-npm">How do I install node with npm?</h2>
 263
 264 <p>You don&#39;t.  Try one of these node version managers:</p>
 265
 266 <p>Unix:</p>
 267
 268 <ul><li><a href="http://github.com/isaacs/nave">http://github.com/isaacs/nave</a></li><li><a href="http://github.com/visionmedia/n">http://github.com/visionmedia/n</a></li><li><a href="http://github.com/creationix/nvm">http://github.com/creationix/nvm</a></li></ul>
 269
 270 <p>Windows:</p>
 271
 272 <ul><li><a href="http://github.com/marcelklehr/nodist">http://github.com/marcelklehr/nodist</a></li><li><a href="https://github.com/hakobera/nvmw">https://github.com/hakobera/nvmw</a></li></ul>
 273
 274 <h2 id="How-can-I-use-npm-for-development">How can I use npm for development?</h2>
 275
 276 <p>See <code><a href="../misc/npm-developers.html">npm-developers(7)</a></code> and <code><a href="../files/package.json.html">package.json(5)</a></code>.</p>
 277
 278 <p>You&#39;ll most likely want to <code>npm link</code> your development folder.  That&#39;s
 279 awesomely handy.</p>
 280
 281 <p>To set up your own private registry, check out <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
 282
 283 <h2 id="Can-I-list-a-url-as-a-dependency">Can I list a url as a dependency?</h2>
 284
 285 <p>Yes.  It should be a url to a gzipped tarball containing a single folder
 286 that has a package.json in its root, or a git url.
 287 (See &quot;what is a package?&quot; above.)</p>
 288
 289 <h2 id="How-do-I-symlink-to-a-dev-folder-so-I-don-t-have-to-keep-re-installing">How do I symlink to a dev folder so I don&#39;t have to keep re-installing?</h2>
 290
 291 <p>See <code><a href="../cli/npm-link.html">npm-link(1)</a></code></p>
 292
 293 <h2 id="The-package-registry-website-What-is-that-exactly">The package registry website.  What is that exactly?</h2>
 294
 295 <p>See <code><a href="../misc/npm-registry.html">npm-registry(7)</a></code>.</p>
 296
 297 <h2 id="I-forgot-my-password-and-can-t-publish-How-do-I-reset-it">I forgot my password, and can&#39;t publish.  How do I reset it?</h2>
 298
 299 <p>Go to <a href="https://npmjs.org/forgot">https://npmjs.org/forgot</a>.</p>
 300
 301 <h2 id="I-get-ECONNREFUSED-a-lot-What-s-up">I get ECONNREFUSED a lot.  What&#39;s up?</h2>
 302
 303 <p>Either the registry is down, or node&#39;s DNS isn&#39;t able to reach out.</p>
 304
 305 <p>To check if the registry is down, open up <a href="http://registry.npmjs.org/">http://registry.npmjs.org/</a>
 306 in a web browser.  This will also tell you if you are just unable to
 307 access the internet for some reason.</p>
 308
 309 <p>If the registry IS down, let me know by emailing <a href="mailto:i@izs.me">i@izs.me</a> or posting
 310 an issue at <a href="https://github.com/isaacs/npm/issues">https://github.com/isaacs/npm/issues</a>.  We&#39;ll have
 311 someone kick it or something.</p>
 312
 313 <h2 id="Why-no-namespaces">Why no namespaces?</h2>
 314
 315 <p>Please see this discussion: <a href="https://github.com/isaacs/npm/issues/798">https://github.com/isaacs/npm/issues/798</a></p>
 316
 317 <p>tl;dr - It doesn&#39;t actually make things better, and can make them worse.</p>
 318
 319 <p>If you want to namespace your own packages, you may: simply use the
 320 <code>-</code> character to separate the names.  npm is a mostly anarchic system.
 321 There is not sufficient need to impose namespace rules on everyone.</p>
 322
 323 <h2 id="Who-does-npm">Who does npm?</h2>
 324
 325 <p><code>npm view npm author</code></p>
 326
 327 <p><code>npm view npm contributors</code></p>
 328
 329 <h2 id="I-have-a-question-or-request-not-addressed-here-Where-should-I-put-it">I have a question or request not addressed here. Where should I put it?</h2>
 330
 331 <p>Post an issue on the github project:</p>
 332
 333 <ul><li><a href="https://github.com/isaacs/npm/issues">https://github.com/isaacs/npm/issues</a></li></ul>
 334
 335 <h2 id="Why-does-npm-hate-me">Why does npm hate me?</h2>
 336
 337 <p>npm is not capable of hatred.  It loves everyone, especially you.</p>
 338
 339 <h2 id="SEE-ALSO">SEE ALSO</h2>
 340
 341 <ul><li><a href="../cli/npm.html">npm(1)</a></li><li><a href="../misc/npm-developers.html">npm-developers(7)</a></li><li><a href="../files/package.json.html">package.json(5)</a></li><li><a href="../cli/npm-config.html">npm-config(1)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../files/npmrc.html">npmrc(5)</a></li><li><a href="../misc/npm-config.html">npm-config(7)</a></li><li><a href="../files/npm-folders.html">npm-folders(5)</a></li></ul>
 342 </div>
 343 <p id="footer">npm-faq &mdash; npm@1.3.15</p>
 344 <script>
 345 ;(function () {
 346 var wrapper = document.getElementById("wrapper")
 347 var els = Array.prototype.slice.call(wrapper.getElementsByTagName("*"), 0)
 348   .filter(function (el) {
 349     return el.parentNode === wrapper
 350         && el.tagName.match(/H[1-6]/)
 351         && el.id
 352   })
 353 var l = 2
 354   , toc = document.createElement("ul")
 355 toc.innerHTML = els.map(function (el) {
 356   var i = el.tagName.charAt(1)
 357     , out = ""
 358   while (i > l) {
 359     out += "<ul>"
 360     l ++
 361   }
 362   while (i < l) {
 363     out += "</ul>"
 364     l --
 365   }
 366   out += "<li><a href='#" + el.id + "'>" +
 367     ( el.innerText || el.text || el.innerHTML)
 368     + "</a>"
 369   return out
 370 }).join("\n")
 371 toc.id = "toc"
 372 document.body.appendChild(toc)
 373 })()
 374 </script>