|
| 1 | +npm-folders(1) -- Folder Structures Used by npm |
| 2 | +=============================================== |
| 3 | + |
| 4 | +## DESCRIPTION |
| 5 | + |
| 6 | +npm puts various things on your computer. That's its job. |
| 7 | + |
| 8 | +This document will tell you what it puts where. |
| 9 | + |
| 10 | +### tl;dr |
| 11 | + |
| 12 | +* Local install (default): puts stuff in `./node_modules` of the current |
| 13 | + package root. |
| 14 | +* Global install (with `-g`): puts stuff in /usr/local or wherever node |
| 15 | + is installed. |
| 16 | +* Install it **locally** if you're going to `require()` it. |
| 17 | +* Install it **globally** if you're going to run it on the command line. |
| 18 | +* If you need both, then install it in both places, or use `npm link`. |
| 19 | + |
| 20 | +### prefix Configuration |
| 21 | + |
| 22 | +The `prefix` config defaults to the location where node is installed. |
| 23 | +On most systems, this is `/usr/local`, and most of the time is the same |
| 24 | +as node's `process.installPrefix`. |
| 25 | + |
| 26 | +On windows, this is the exact location of the node.exe binary. On Unix |
| 27 | +systems, it's one level up, since node is typically installed at |
| 28 | +`{prefix}/bin/node` rather than `{prefix}/node.exe`. |
| 29 | + |
| 30 | +When the `global` flag is set, npm installs things into this prefix. |
| 31 | +When it is not set, it uses the root of the current package, or the |
| 32 | +current working directory if not in a package already. |
| 33 | + |
| 34 | +### Node Modules |
| 35 | + |
| 36 | +Packages are dropped into the `node_modules` folder under the `prefix`. |
| 37 | +When installing locally, this means that you can |
| 38 | +`require("packagename")` to load its main module, or |
| 39 | +`require("packagename/lib/path/to/sub/module")` to load other modules. |
| 40 | + |
| 41 | +Global installs on Unix systems go to `{prefix}/lib/node_modules`. |
| 42 | +Global installs on Windows go to `{prefix}/node_modules` (that is, no |
| 43 | +`lib` folder.) |
| 44 | + |
| 45 | +If you wish to `require()` a package, then install it locally. |
| 46 | + |
| 47 | +### Executables |
| 48 | + |
| 49 | +When in global mode, executables are linked into `{prefix}/bin` on Unix, |
| 50 | +or directly into `{prefix}` on Windows. |
| 51 | + |
| 52 | +When in local mode, executables are linked into |
| 53 | +`./node_modules/.bin` so that they can be made available to scripts run |
| 54 | +through npm. (For example, so that a test runner will be in the path |
| 55 | +when you run `npm test`.) |
| 56 | + |
| 57 | +### Man Pages |
| 58 | + |
| 59 | +When in global mode, man pages are linked into `{prefix}/share/man`. |
| 60 | + |
| 61 | +When in local mode, man pages are not installed. |
| 62 | + |
| 63 | +Man pages are not installed on Windows systems. |
| 64 | + |
| 65 | +### Cache |
| 66 | + |
| 67 | +See `npm-cache(1)`. Cache files are stored in `~/.npm` on Posix, or |
| 68 | +`~/npm-cache` on Windows. |
| 69 | + |
| 70 | +This is controlled by the `cache` configuration param. |
| 71 | + |
| 72 | +### Temp Files |
| 73 | + |
| 74 | +Temporary files are stored by default in the folder specified by the |
| 75 | +`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment |
| 76 | +variables, or `/tmp` on Unix and `c:\windows\temp` on Windows. |
| 77 | + |
| 78 | +Temp files are given a unique folder under this root for each run of the |
| 79 | +program, and are deleted upon successful exit. |
| 80 | + |
| 81 | +## More Information |
| 82 | + |
| 83 | +When installing locally, npm first tries to find an appropriate |
| 84 | +`prefix` folder. This is so that `npm install [email protected]` will install |
| 85 | +to the sensible root of your package, even if you happen to have `cd`ed |
| 86 | +into some other folder. |
| 87 | + |
| 88 | +Starting at the $PWD, npm will walk up the folder tree checking for a |
| 89 | +folder that contains either a `package.json` file, or a `node_modules` |
| 90 | +folder. If such a thing is found, then that is treated as the effective |
| 91 | +"current directory" for the purpose of running npm commands. (This |
| 92 | +behavior is inspired by and similar to git's .git-folder seeking |
| 93 | +logic when running git commands in a working dir.) |
| 94 | + |
| 95 | +If no package root is found, then the current folder is used. |
| 96 | + |
| 97 | +When you run `npm install [email protected]`, then the package is loaded into |
| 98 | +the cache, and then unpacked into `./node_modules/foo`. Then, any of |
| 99 | +foo's dependencies are similarly unpacked into |
| 100 | +`./node_modules/foo/node_modules/...`. |
| 101 | + |
| 102 | +Any bin files are symlinked to `./node_modules/.bin/`, so that they may |
| 103 | +be found by npm scripts when necessary. |
| 104 | + |
| 105 | +### Global Installation |
| 106 | + |
| 107 | +If the `global` configuration is set to true, then npm will |
| 108 | +install packages "globally". |
| 109 | + |
| 110 | +For global installation, packages are installed roughly the same way, |
| 111 | +but using the folders described above. |
| 112 | + |
| 113 | +### Cycles, Conflicts, and Folder Parsimony |
| 114 | + |
| 115 | +Cycles are handled using the property of node's module system that it |
| 116 | +walks up the directories looking for `node_modules` folders. So, at every |
| 117 | +stage, if a package is already installed in an ancestor `node_modules` |
| 118 | +folder, then it is not installed at the current location. |
| 119 | + |
| 120 | +Consider the case above, where `foo -> bar -> baz`. Imagine if, in |
| 121 | +addition to that, baz depended on bar, so you'd have: |
| 122 | +`foo -> bar -> baz -> bar -> baz ...`. However, since the folder |
| 123 | +structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to |
| 124 | +put another copy of bar into `.../baz/node_modules`, since when it calls |
| 125 | +require("bar"), it will get the copy that is installed in |
| 126 | +`foo/node_modules/bar`. |
| 127 | + |
| 128 | +This shortcut is only used if the exact same |
| 129 | +version would be installed in multiple nested `node_modules` folders. It |
| 130 | +is still possible to have `a/node_modules/b/node_modules/a` if the two |
| 131 | +"a" packages are different versions. However, without repeating the |
| 132 | +exact same package multiple times, an infinite regress will always be |
| 133 | +prevented. |
| 134 | + |
| 135 | +Another optimization can be made by installing dependencies at the |
| 136 | +highest level possible, below the localized "target" folder. |
| 137 | + |
| 138 | +#### Example |
| 139 | + |
| 140 | +Consider this dependency graph: |
| 141 | + |
| 142 | + foo |
| 143 | + |
| 144 | + |
| 145 | + | +-- [email protected] (latest=1.3.7) |
| 146 | + |
| 147 | + |
| 148 | + |
| 149 | + | `-- asdf@* |
| 150 | + |
| 151 | + |
| 152 | + `-- bar |
| 153 | + |
| 154 | +In this case, we might expect a folder structure like this: |
| 155 | + |
| 156 | + foo |
| 157 | + +-- node_modules |
| 158 | + +-- blerg (1.2.5) <---[A] |
| 159 | + +-- bar (1.2.3) <---[B] |
| 160 | + | +-- node_modules |
| 161 | + | | `-- baz (2.0.2) <---[C] |
| 162 | + | | `-- node_modules |
| 163 | + | | `-- quux (3.2.0) |
| 164 | + | `-- asdf (2.3.4) |
| 165 | + `-- baz (1.2.3) <---[D] |
| 166 | + `-- node_modules |
| 167 | + `-- quux (3.2.0) <---[E] |
| 168 | + |
| 169 | +Since foo depends directly on [email protected] and [email protected], those are |
| 170 | +installed in foo's `node_modules` folder. |
| 171 | + |
| 172 | +Even though the latest copy of blerg is 1.3.7, foo has a specific |
| 173 | +dependency on version 1.2.5. So, that gets installed at [A]. Since the |
| 174 | +parent installation of blerg satisfie's bar's dependency on [email protected], |
| 175 | +it does not install another copy under [B]. |
| 176 | + |
| 177 | +Bar [B] also has dependencies on baz and asdf, so those are installed in |
| 178 | +bar's `node_modules` folder. Because it depends on `[email protected]`, it cannot |
| 179 | +re-use the `[email protected]` installed in the parent `node_modules` folder [D ], |
| 180 | +and must install its own copy [C]. |
| 181 | + |
| 182 | +Underneath bar, the `baz->quux->bar` dependency creates a cycle. |
| 183 | +However, because `bar` is already in `quux`'s ancestry [B], it does not |
| 184 | +unpack another copy of bar into that folder. |
| 185 | + |
| 186 | +Underneath `foo->baz` [D], quux's [E] folder tree is empty, because its |
| 187 | +dependency on bar is satisfied by the parent folder copy installed at [B]. |
| 188 | + |
| 189 | +For a graphical breakdown of what is installed where, use `npm ls`. |
| 190 | + |
| 191 | +### Publishing |
| 192 | + |
| 193 | +Upon publishing, npm will look in the `node_modules` folder. If any of |
| 194 | +the items there are not in the `bundledDependencies` array, then they will |
| 195 | +not be included in the package tarball. |
| 196 | + |
| 197 | +This allows a package maintainer to install all of their dependencies |
| 198 | +(and dev dependencies) locally, but only re-publish those items that |
| 199 | +cannot be found elsewhere. See `npm-json(1)` for more information. |
| 200 | + |
| 201 | +## SEE ALSO |
| 202 | + |
| 203 | +* npm-faq(1) |
| 204 | +* npm-json(1) |
| 205 | +* npm-install(1) |
| 206 | +* npm-pack(1) |
| 207 | +* npm-cache(1) |
| 208 | +* npm-config(1) |
| 209 | +* npm-publish(1) |
0 commit comments