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

NAME

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