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