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         +-- package.json
101
102       You may generate a new workspace using the legacy init:
103
104         $ npm init -w packages/a
105
106       That  will  generate a new folder and package.json file, while also up‐
107       dating your top-level package.json to add the  reference  to  this  new
108       workspace:
109
110         +-- package.json
111         `-- packages
112            `-- a
113                `-- package.json
114
115       The  workspaces  init also supports the npm init <initializer> -w <dir>
116       syntax, following the same set of rules explained earlier in  the  ini‐
117       tial  Description section of this page. Similar to the previous example
118       of  creating  a  new   React-based   project   using   create-react-app
119       ⟨https://npm.im/create-react-app⟩,  the following syntax will make sure
120       to create the new react app as a nested workspace within  your  project
121       and configure your package.json to recognize it as such:
122
123         npm init -w packages/my-react-app react-app .
124
125       This  will make sure to generate your react app as expected, one impor‐
126       tant consideration to have in mind is that npm exec is going to be  run
127       in  the  context  of  the  newly created folder for that workspace, and
128       that's the reason why in this example the initializer uses the initial‐
129       izer  name  followed  with  a dot to represent the current directory in
130       that context, e.g: react-app .:
131
132         +-- package.json
133         `-- packages
134            +-- a
135            |   `-- package.json
136            `-- my-react-app
137                +-- README
138                +-- package.json
139                `-- ...
140
141   Configuration
142   init-author-name
143       •   Default: ""
144
145       •   Type: String
146
147
148       The value npm init should use by default for the package author's name.
149
150   init-author-url
151       •   Default: ""
152
153       •   Type: "" or URL
154
155
156       The value npm init should use by default for the package author's home‐
157       page.
158
159   init-license
160       •   Default: "ISC"
161
162       •   Type: String
163
164
165       The value npm init should use by default for the package license.
166
167   init-module
168       •   Default: "~/.npm-init.js"
169
170       •   Type: Path
171
172
173       A  module that will be loaded by the npm init command. See the documen‐
174       tation for the init-package-json  ⟨https://github.com/npm/init-package-
175       json⟩ module for more information, or npm help init.
176
177   init-version
178       •   Default: "1.0.0"
179
180       •   Type: SemVer string
181
182
183       The  value  that npm init should use by default for the package version
184       number, if not already set in package.json.
185
186   yes
187       •   Default: null
188
189       •   Type: null or Boolean
190
191
192       Automatically answer "yes" to any prompts that npm might print  on  the
193       command line.
194
195   force
196       •   Default: false
197
198       •   Type: Boolean
199
200
201       Removes  various  protections  against unfortunate side effects, common
202       mistakes, unnecessary performance degradation, and malicious input.
203
204       •   Allow clobbering non-npm files in global installs.
205
206       •   Allow the npm version command to work on an unclean git repository.
207
208       •   Allow deleting the cache folder with npm cache clean.
209
210       •   Allow installing packages that have an engines declaration  requir‐
211           ing a different version of npm.
212
213       •   Allow  installing packages that have an engines declaration requir‐
214           ing a different version of node, even  if  --engine-strict  is  en‐
215           abled.
216
217       •   Allow  npm  audit fix to install modules outside your stated depen‐
218           dency range (including SemVer-major changes).
219
220       •   Allow unpublishing all versions of a published package.
221
222       •   Allow conflicting peerDependencies to  be  installed  in  the  root
223           project.
224
225       •   Implicitly set --yes during npm init.
226
227       •   Allow clobbering existing values in npm pkg
228
229       •   Allow unpublishing of entire packages (not just a single version).
230
231
232       If  you  don't have a clear idea of what you want to do, it is strongly
233       recommended that you do not use this option!
234
235   scope
236       •   Default: the scope of the current project, if any, or ""
237
238       •   Type: String
239
240
241       Associate an operation with a scope for a scoped registry.
242
243       Useful when logging in to or out of a private registry:
244
245         # log in, linking the scope to the custom registry
246         npm login --scope=@mycorp --registry=https://registry.mycorp.com
247
248         # log out, removing the link and the auth token
249         npm logout --scope=@mycorp
250
251       This will cause @mycorp to be mapped to the registry for future instal‐
252       lation of packages specified according to the pattern @mycorp/package.
253
254       This will also cause npm init to create a scoped package.
255
256         # accept all defaults, and create a package named "@foo/whatever",
257         # instead of just named "whatever"
258         npm init --scope=@foo --yes
259
260   workspace
261       •   Default:
262
263       •   Type: String (can be set multiple times)
264
265
266       Enable running a command in the context of the configured workspaces of
267       the current project while filtering by running only the workspaces  de‐
268       fined by this configuration option.
269
270       Valid values for the workspace config are either:
271
272       •   Workspace names
273
274       •   Path to a workspace directory
275
276       •   Path  to a parent workspace directory (will result in selecting all
277           workspaces within that folder)
278
279
280       When set for the npm init command, this may be set to the folder  of  a
281       workspace  which does not yet exist, to create the folder and set it up
282       as a brand new workspace within the project.
283
284       This value is not exported to the environment for child processes.
285
286   workspaces
287       •   Default: null
288
289       •   Type: null or Boolean
290
291
292       Set to true to run  the  command  in  the  context  of  all  configured
293       workspaces.
294
295       Explicitly  setting  this  to false will cause commands like install to
296       ignore workspaces altogether. When not set explicitly:
297
298       •   Commands that operate on the node_modules  tree  (install,  update,
299           etc.) will link workspaces into the node_modules folder. - Commands
300           that do other things (test, exec, publish, etc.)  will  operate  on
301           the  root  project,  unless one or more workspaces are specified in
302           the workspace config.
303
304
305       This value is not exported to the environment for child processes.
306
307   workspaces-update
308       •   Default: true
309
310       •   Type: Boolean
311
312
313       If set to true, the npm cli will run an update  after  operations  that
314       may  possibly  change  the  workspaces  installed  to  the node_modules
315       folder.
316
317   include-workspace-root
318       •   Default: false
319
320       •   Type: Boolean
321
322
323       Include the workspace root when workspaces are enabled for a command.
324
325       When false, specifying individual workspaces via the workspace  config,
326       or  all  workspaces  via the workspaces flag, will cause npm to operate
327       only on the specified workspaces, and not on the root project.
328
329       This value is not exported to the environment for child processes.
330
331   See Also
332       •   npm help "package spec"
333
334       •   init-package-json module ⟨http://npm.im/init-package-json⟩
335
336       •   package.json ⟨/configuring-npm/package-json⟩
337
338       •   npm help version
339
340       •   npm help scope
341
342       •   npm help exec
343
344       •   npm help workspaces
345
346
347
348                                 November 2023                     NPM-INIT(1)