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 to selecting all of
203         the nested workspaces)
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: false
217
218       • Type: Boolean
219
220
221       Enable  running  a  command  in  the  context  of  all  the  configured
222       workspaces.
223
224       This  value  is  not  exported  to the environment for child processes.
225       <!-- automatically  generated,  do  not  edit  manually  -->  <!--  see
226       lib/utils/config/definitions.js -->
227
228       <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
229
230
231   See Also
232       • init-package-json module http://npm.im/init-package-json
233
234       • npm help package.json
235
236       • npm help version
237
238       • npm help scope
239
240       • npm help exec
241
242       • npm help workspaces
243
244
245
246
247                                 October 2021                      NPM-INIT(1)