1NPM-INIT(1)                                                        NPM-INIT(1)
2
3
4

NAME

6       npm-init - Create a package.json file
7
8   Synopsis
9         npm init <package-spec> (same as `npx <package-spec>)
10         npm init <@scope> (same as `npx <@scope>/create`)
11
12         aliases: create, innit
13
14   Description
15       npm  init  <initializer>  can  be  used to set up a new or existing npm
16       package.
17
18       initializer in this case is an npm package named  create-<initializer>,
19       which  will  be  installed by npm help npm-exec, and then have its main
20       bin executed -- presumably creating or updating package.json  and  run‐
21       ning any other initialization-related operations.
22
23       The  init  command is transformed to a corresponding npm exec operation
24       as follows:
25
26       • npm init foo -> npm exec create-foo
27
28       • npm init @usr/foo -> npm exec @usr/create-foo
29
30       • npm init @usr -> npm exec @usr/create
31
32       • npm init @usr@2.0.0 -> npm exec @usr/create@2.0.0
33
34       • npm init @usr/foo@2.0.0 -> npm exec @usr/create-foo@2.0.0
35
36
37       If the initializer is omitted (by just calling  npm  init),  init  will
38       fall  back  to  legacy  init behavior. It will ask you a bunch of ques‐
39       tions, and then write a package.json for you. It will attempt  to  make
40       reasonable  guesses based on existing fields, dependencies, and options
41       selected. It is strictly additive, so it will keep any fields and  val‐
42       ues  that were already set. You can also use -y/--yes to skip the ques‐
43       tionnaire altogether. If you pass --scope,  it  will  create  a  scoped
44       package.
45
46       Note:  if  a user already has the create-<initializer> package globally
47       installed, that will be what npm init uses.  If you want npm to use the
48       latest version, or another specific version you must specify it:
49
50       • npm init foo@latest # fetches and runs the latest create-foo from
51           the registry
52
53       • npm init foo@1.2.3 #  runs create-foo@1.2.3 specifically
54
55
56   Forwarding additional options
57       Any  additional  options will be passed directly to the command, so npm
58       init foo -- --hello will map to npm exec -- create-foo --hello.
59
60       To better illustrate how options are forwarded, here's a  more  evolved
61       example  showing  options passed to both the npm cli and a create pack‐
62       age, both following commands are equivalent:
63
64       • npm init foo -y --registry=<url> -- --hello -a
65
66       • npm exec -y --registry=<url> -- create-foo --hello -a
67
68
69   Examples
70       Create   a   new    React-based    project    using    create-react-app
71       https://npm.im/create-react-app:
72
73         $ npm init react-app ./my-react-app
74
75       Create     a    new    esm-compatible    package    using    create-esm
76       https://npm.im/create-esm:
77
78         $ mkdir my-esm-lib && cd my-esm-lib
79         $ npm init esm --yes
80
81       Generate a plain old package.json using legacy init:
82
83         $ mkdir my-npm-pkg && cd my-npm-pkg
84         $ git init
85         $ npm init
86
87       Generate it without having it ask any questions:
88
89         $ npm init -y
90
91   Workspaces support
92       It's possible to create a new workspace within your  project  by  using
93       the  workspace config option. When using npm init -w <dir> the cli will
94       create the folders and boilerplate expected while also adding a  refer‐
95       ence to your project package.json "workspaces": [] property in order to
96       make sure that new generated workspace is properly set up as such.
97
98       Given a project with no workspaces, e.g:
99
100         .
101         +-- package.json
102
103       You may generate a new workspace using the legacy init:
104
105         $ npm init -w packages/a
106
107       That will generate a new folder and package.json file, while  also  up‐
108       dating  your  top-level  package.json  to add the reference to this new
109       workspace:
110
111         .
112         +-- package.json
113         `-- packages
114            `-- a
115                `-- package.json
116
117       The workspaces init also supports the npm init <initializer>  -w  <dir>
118       syntax,  following  the same set of rules explained earlier in the ini‐
119       tial Description section of this page. Similar to the previous  example
120       of   creating   a   new   React-based  project  using  create-react-app
121       https://npm.im/create-react-app, the following syntax will make sure to
122       create  the new react app as a nested workspace within your project and
123       configure your package.json to recognize it as such:
124
125         npm init -w packages/my-react-app react-app .
126
127       This will make sure to generate your react app as expected, one  impor‐
128       tant  consideration to have in mind is that npm exec is going to be run
129       in the context of the newly created  folder  for  that  workspace,  and
130       that's the reason why in this example the initializer uses the initial‐
131       izer name followed with a dot to represent  the  current  directory  in
132       that context, e.g: react-app .:
133
134         .
135         +-- package.json
136         `-- packages
137            +-- a
138            |   `-- package.json
139            `-- my-react-app
140                +-- README
141                +-- package.json
142                `-- ...
143
144   Configuration
145   yes
146       • Default: null
147
148       • Type: null or Boolean
149
150
151       Automatically  answer  "yes" to any prompts that npm might print on the
152       command line.
153
154   force
155       • Default: false
156
157       • Type: Boolean
158
159
160       Removes various protections against unfortunate  side  effects,  common
161       mistakes, unnecessary performance degradation, and malicious input.
162
163       • Allow clobbering non-npm files in global installs.
164
165       • Allow the npm version command to work on an unclean git repository.
166
167       • Allow deleting the cache folder with npm cache clean.
168
169       • Allow  installing packages that have an engines declaration requiring
170         a different version of npm.
171
172       • Allow installing packages that have an engines declaration  requiring
173         a different version of node, even if --engine-strict is enabled.
174
175       • Allow npm audit fix to install modules outside your stated dependency
176         range (including SemVer-major changes).
177
178       • Allow unpublishing all versions of a published package.
179
180       • Allow conflicting  peerDependencies  to  be  installed  in  the  root
181         project.
182
183       • Implicitly set --yes during npm init.
184
185       • Allow clobbering existing values in npm pkg
186
187       • Allow unpublishing of entire packages (not just a single version).
188
189
190       If  you  don't have a clear idea of what you want to do, it is strongly
191       recommended that you do not use this option!
192
193   scope
194       • Default: the scope of the current project, if any, or ""
195
196       • Type: String
197
198
199       Associate an operation with a scope for a scoped registry.
200
201       Useful when logging in to or out of a private registry:
202
203         # log in, linking the scope to the custom registry
204         npm login --scope=@mycorp --registry=https://registry.mycorp.com
205
206         # log out, removing the link and the auth token
207         npm logout --scope=@mycorp
208
209       This will cause @mycorp to be mapped to the registry for future instal‐
210       lation of packages specified according to the pattern @mycorp/package.
211
212       This will also cause npm init to create a scoped package.
213
214         # accept all defaults, and create a package named "@foo/whatever",
215         # instead of just named "whatever"
216         npm init --scope=@foo --yes
217
218   workspace
219       • Default:
220
221       • Type: String (can be set multiple times)
222
223
224       Enable running a command in the context of the configured workspaces of
225       the current project while filtering by running only the workspaces  de‐
226       fined by this configuration option.
227
228       Valid values for the workspace config are either:
229
230       • Workspace names
231
232       • Path to a workspace directory
233
234       • Path  to  a  parent workspace directory (will result in selecting all
235         workspaces within that folder)
236
237
238       When set for the npm init command, this may be set to the folder  of  a
239       workspace  which does not yet exist, to create the folder and set it up
240       as a brand new workspace within the project.
241
242       This value is not exported to the environment for child processes.
243
244   workspaces
245       • Default: null
246
247       • Type: null or Boolean
248
249
250       Set to true to run  the  command  in  the  context  of  all  configured
251       workspaces.
252
253       Explicitly  setting  this  to false will cause commands like install to
254       ignore workspaces altogether. When not set explicitly:
255
256       • Commands that operate on  the  node_modules  tree  (install,  update,
257         etc.)   will link workspaces into the node_modules folder. - Commands
258         that do other things (test, exec, publish, etc.) will operate on  the
259         root  project,  unless  one  or  more workspaces are specified in the
260         workspace config.
261
262
263       This value is not exported to the environment for child processes.
264
265   workspaces-update
266       • Default: true
267
268       • Type: Boolean
269
270
271       If set to true, the npm cli will run an update  after  operations  that
272       may  possibly  change  the  workspaces  installed  to  the node_modules
273       folder.
274
275   include-workspace-root
276       • Default: false
277
278       • Type: Boolean
279
280
281       Include the workspace root when workspaces are enabled for a command.
282
283       When false, specifying individual workspaces via the workspace  config,
284       or  all  workspaces  via the workspaces flag, will cause npm to operate
285       only on the specified workspaces, and not on the root project.
286
287       This value is not exported to the environment for child processes.
288
289   See Also
290       • npm help package spec
291
292       • init-package-json module http://npm.im/init-package-json
293
294       • npm help package.json
295
296       • npm help version
297
298       • npm help scope
299
300       • npm help exec
301
302       • npm help workspaces
303
304
305
306
307                                September 2022                     NPM-INIT(1)