1FOLDERS(5)                                                          FOLDERS(5)
2
3
4

NAME

6       folders - Folder Structures Used by npm
7
8   Description
9       npm puts various things on your computer.  That's its job.
10
11       This document will tell you what it puts where.
12
13   tl;dr
14       • Local  install (default): puts stuff in ./node_modules of the current
15         package root.
16
17       • Global install (with -g): puts stuff in /usr/local or  wherever  node
18         is installed.
19
20       • Install it locally if you're going to require() it.
21
22       • Install it globally if you're going to run it on the command line.
23
24       • If you need both, then install it in both places, or use npm link.
25
26
27   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
33       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
37   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
43       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
47       Scoped packages are installed the same way, except they are grouped to‐
48       gether 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 @my‐
50       org/package  would  place  the  package  in  {prefix}/node_modules/@my‐
51       org/package. See npm help scope for more details.
52
53       If you wish to require() a package, then install it locally.
54
55   Executables
56       When  in global mode, executables are linked into {prefix}/bin on Unix,
57       or directly into {prefix} on Windows.
58
59       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
63   Man Pages
64       When in global mode, man pages are linked into {prefix}/share/man.
65
66       When in local mode, man pages are not installed.
67
68       Man pages are not installed on Windows systems.
69
70   Cache
71       See npm help cache.  Cache files are stored in ~/.npm on Posix, or %Ap‐
72       pData%/npm-cache on Windows.
73
74       This is controlled by the cache configuration param.
75
76   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
81       Temp  files  are  given a unique folder under this root for each run of
82       the program, and are deleted upon successful exit.
83
84   More Information
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
90       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
97       If no package root is found, then the current folder is used.
98
99       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
104       Any  bin  files are symlinked to ./node_modules/.bin/, so that they may
105       be found by npm scripts when necessary.
106
107   Global Installation
108       If the global configuration is set to true, then npm will install pack‐
109       ages "globally".
110
111       For  global  installation, packages are installed roughly the same way,
112       but using the folders described above.
113
114   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 ev‐
117       ery 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
120       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
127       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
133       Another optimization can be made  by  installing  dependencies  at  the
134       highest level possible, below the localized "target" folder.
135
136   Example
137       Consider this dependency graph:
138
139         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
151       In this case, we might expect a folder structure like this:
152
153         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
166       Since  foo  depends  directly on bar@1.2.3 and baz@1.2.3, those are in‐
167       stalled in foo's node_modules folder.
168
169       Even though the latest copy of blerg is 1.3.7, foo has a  specific  de‐
170       pendency  on version 1.2.5.  So, that gets installed at [A].  Since the
171       parent installation of blerg satisfies bar's dependency  on  blerg@1.x,
172       it does not install another copy under [B].
173
174       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
179       Underneath bar, the baz -> quux ->  bar  dependency  creates  a  cycle.
180       However, because bar is already in quux's ancestry [B], it does not un‐
181       pack another copy of bar into that folder.
182
183       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
187       For a graphical breakdown of what is installed where, use npm ls.
188
189   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
194       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 package.json for more informa‐
197       tion.
198
199   See also
200       • npm help package.json
201
202       • npm help install
203
204       • npm help pack
205
206       • npm help cache
207
208       • npm help config
209
210       • npm help npmrc
211
212       • npm help config
213
214       • npm help publish
215
216
217
218
219                                  April 2021                        FOLDERS(5)
Impressum