cli: add auto-generated cli docs

content/cli/v7/commands/index.mdx

+1 -6

@@ -1,11 +1,6 @@

1 ---

2 -redirect_from:

3 - - commands

4 - - /cli/commands

5 - - /cli-documentation/cli

6 - - /cli-documentation/cli-commands

2 github_repo: npm/cli

8 -github_branch: latest

3 +github_branch: v7

4 github_path: docs/content/commands/index.mdx

5 title: CLI commands

6 ---

content/cli/v7/commands/npm-access.md

+1 -9

@@ -2,16 +2,8 @@

2 title: npm-access

3 section: 1

4 description: Set access level on published packages

5 -redirect_from:

6 - - /cli/access

7 - - /cli/access.html

8 - - /cli/commands/access

9 - - /cli-commands/access

10 - - /cli-commands/access.html

11 - - /cli-commands/npm-access

12 - - /cli-documentation/access

5 github_repo: npm/cli

14 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-access.md

8 ---

9

content/cli/v7/commands/npm-adduser.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-adduser

3 section: 1

4 description: Add a registry user account

5 -redirect_from:

6 - - /cli/adduser

7 - - /cli/adduser.html

8 - - /cli/commands/adduser

9 - - /cli-commands/adduser

10 - - /cli-commands/adduser.html

11 - - /cli-commands/npm-adduser

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-adduser.md

8 ---

9

content/cli/v7/commands/npm-audit.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-audit

3 section: 1

4 description: Run a security audit

5 -redirect_from:

6 - - /cli/audit

7 - - /cli/audit.html

8 - - /cli/commands/audit

9 - - /cli-commands/audit

10 - - /cli-commands/audit.html

11 - - /cli-commands/npm-audit

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-audit.md

8 ---

9

@@ -323,8 +316,8 @@ Valid values for the `workspace` config are either:

316

317 * Workspace names

318 * Path to a workspace directory

326 -* Path to a parent workspace directory (will result in selecting all

327 - workspaces within that folder)

319 +* Path to a parent workspace directory (will result to selecting all of the

320 + nested workspaces)

321

322 When set for the `npm init` command, this may be set to the folder of a

323 workspace which does not yet exist, to create the folder and set it up as a

@@ -337,35 +330,13 @@ This value is not exported to the environment for child processes.

330

331 #### `workspaces`

332

340 -* Default: null

341 -* Type: null or Boolean

342 -

343 -Set to true to run the command in the context of **all** configured

344 -workspaces.

345 -

346 -Explicitly setting this to false will cause commands like `install` to

347 -ignore workspaces altogether. When not set explicitly:

348 -

349 -- Commands that operate on the `node_modules` tree (install, update, etc.)

350 -will link workspaces into the `node_modules` folder. - Commands that do

351 -other things (test, exec, publish, etc.) will operate on the root project,

352 -_unless_ one or more workspaces are specified in the `workspace` config.

353 -

354 -This value is not exported to the environment for child processes.

355 -

356 -<!-- automatically generated, do not edit manually -->

357 -<!-- see lib/utils/config/definitions.js -->

358 -

359 -#### `include-workspace-root`

360 -

333 * Default: false

334 * Type: Boolean

335

364 -Include the workspace root when workspaces are enabled for a command.

336 +Enable running a command in the context of **all** the configured

337 +workspaces.

338

366 -When false, specifying individual workspaces via the `workspace` config, or

367 -all workspaces via the `workspaces` flag, will cause npm to operate only on

368 -the specified workspaces, and not on the root project.

339 +This value is not exported to the environment for child processes.

340

341 <!-- automatically generated, do not edit manually -->

342 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-bin.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-bin

3 section: 1

4 description: Display npm bin folder

5 -redirect_from:

6 - - /cli/bin

7 - - /cli/bin.html

8 - - /cli/commands/bin

9 - - /cli-commands/bin

10 - - /cli-commands/bin.html

11 - - /cli-commands/npm-bin

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-bin.md

8 ---

9

content/cli/v7/commands/npm-bugs.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-bugs

3 section: 1

4 description: Report bugs for a package in a web browser

5 -redirect_from:

6 - - /cli/bugs

7 - - /cli/bugs.html

8 - - /cli/commands/bugs

9 - - /cli-commands/bugs

10 - - /cli-commands/bugs.html

11 - - /cli-commands/npm-bugs

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-bugs.md

8 ---

9

content/cli/v7/commands/npm-cache.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-cache

3 section: 1

4 description: Manipulates packages cache

5 -redirect_from:

6 - - /cli/cache

7 - - /cli/cache.html

8 - - /cli/commands/cache

9 - - /cli-commands/cache

10 - - /cli-commands/cache.html

11 - - /cli-commands/npm-cache

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-cache.md

8 ---

9

content/cli/v7/commands/npm-ci.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-ci

3 section: 1

4 description: Install a project with a clean slate

5 -redirect_from:

6 - - /cli/ci

7 - - /cli/ci.html

8 - - /cli/commands/ci

9 - - /cli-commands/ci

10 - - /cli-commands/ci.html

11 - - /cli-commands/npm-ci

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-ci.md

8 ---

9

content/cli/v7/commands/npm-completion.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-completion

3 section: 1

4 description: Tab Completion for npm

5 -redirect_from:

6 - - /cli/completion

7 - - /cli/completion.html

8 - - /cli/commands/completion

9 - - /cli-commands/completion

10 - - /cli-commands/completion.html

11 - - /cli-commands/npm-completion

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-completion.md

8 ---

9

content/cli/v7/commands/npm-config.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-config

3 section: 1

4 description: Manage the npm configuration files

5 -redirect_from:

6 - - /cli/config

7 - - /cli/config.html

8 - - /cli/commands/config

9 - - /cli-commands/config

10 - - /cli-commands/config.html

11 - - /cli-commands/npm-config

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-config.md

8 ---

9

content/cli/v7/commands/npm-dedupe.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-dedupe

3 section: 1

4 description: Reduce duplication in the package tree

5 -redirect_from:

6 - - /cli/dedupe

7 - - /cli/dedupe.html

8 - - /cli/commands/dedupe

9 - - /cli-commands/dedupe

10 - - /cli-commands/dedupe.html

11 - - /cli-commands/npm-dedupe

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-dedupe.md

8 ---

9

@@ -257,8 +250,8 @@ Valid values for the `workspace` config are either:

250

251 * Workspace names

252 * Path to a workspace directory

260 -* Path to a parent workspace directory (will result in selecting all

261 - workspaces within that folder)

253 +* Path to a parent workspace directory (will result to selecting all of the

254 + nested workspaces)

255

256 When set for the `npm init` command, this may be set to the folder of a

257 workspace which does not yet exist, to create the folder and set it up as a

@@ -271,35 +264,13 @@ This value is not exported to the environment for child processes.

264

265 #### `workspaces`

266

274 -* Default: null

275 -* Type: null or Boolean

276 -

277 -Set to true to run the command in the context of **all** configured

278 -workspaces.

279 -

280 -Explicitly setting this to false will cause commands like `install` to

281 -ignore workspaces altogether. When not set explicitly:

282 -

283 -- Commands that operate on the `node_modules` tree (install, update, etc.)

284 -will link workspaces into the `node_modules` folder. - Commands that do

285 -other things (test, exec, publish, etc.) will operate on the root project,

286 -_unless_ one or more workspaces are specified in the `workspace` config.

287 -

288 -This value is not exported to the environment for child processes.

289 -

290 -<!-- automatically generated, do not edit manually -->

291 -<!-- see lib/utils/config/definitions.js -->

292 -

293 -#### `include-workspace-root`

294 -

267 * Default: false

268 * Type: Boolean

269

298 -Include the workspace root when workspaces are enabled for a command.

270 +Enable running a command in the context of **all** the configured

271 +workspaces.

272

300 -When false, specifying individual workspaces via the `workspace` config, or

301 -all workspaces via the `workspaces` flag, will cause npm to operate only on

302 -the specified workspaces, and not on the root project.

273 +This value is not exported to the environment for child processes.

274

275 <!-- automatically generated, do not edit manually -->

276 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-deprecate.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-deprecate

3 section: 1

4 description: Deprecate a version of a package

5 -redirect_from:

6 - - /cli/deprecate

7 - - /cli/deprecate.html

8 - - /cli/commands/deprecate

9 - - /cli-commands/deprecate

10 - - /cli-commands/deprecate.html

11 - - /cli-commands/npm-deprecate

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-deprecate.md

8 ---

9

content/cli/v7/commands/npm-diff.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-diff

3 section: 1

4 description: The registry diff command

5 -redirect_from:

6 - - /cli/diff

7 - - /cli/diff.html

8 - - /cli/commands/diff

9 - - /cli-commands/diff

10 - - /cli-commands/diff.html

11 - - /cli-commands/npm-diff

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-diff.md

8 ---

9

@@ -296,8 +289,8 @@ Valid values for the `workspace` config are either:

289

290 * Workspace names

291 * Path to a workspace directory

299 -* Path to a parent workspace directory (will result in selecting all

300 - workspaces within that folder)

292 +* Path to a parent workspace directory (will result to selecting all of the

293 + nested workspaces)

294

295 When set for the `npm init` command, this may be set to the folder of a

296 workspace which does not yet exist, to create the folder and set it up as a

@@ -310,35 +303,13 @@ This value is not exported to the environment for child processes.

303

304 #### `workspaces`

305

313 -* Default: null

314 -* Type: null or Boolean

315 -

316 -Set to true to run the command in the context of **all** configured

317 -workspaces.

318 -

319 -Explicitly setting this to false will cause commands like `install` to

320 -ignore workspaces altogether. When not set explicitly:

321 -

322 -- Commands that operate on the `node_modules` tree (install, update, etc.)

323 -will link workspaces into the `node_modules` folder. - Commands that do

324 -other things (test, exec, publish, etc.) will operate on the root project,

325 -_unless_ one or more workspaces are specified in the `workspace` config.

326 -

327 -This value is not exported to the environment for child processes.

328 -

329 -<!-- automatically generated, do not edit manually -->

330 -<!-- see lib/utils/config/definitions.js -->

331 -

332 -#### `include-workspace-root`

333 -

306 * Default: false

307 * Type: Boolean

308

337 -Include the workspace root when workspaces are enabled for a command.

309 +Enable running a command in the context of **all** the configured

310 +workspaces.

311

339 -When false, specifying individual workspaces via the `workspace` config, or

340 -all workspaces via the `workspaces` flag, will cause npm to operate only on

341 -the specified workspaces, and not on the root project.

312 +This value is not exported to the environment for child processes.

313

314 <!-- automatically generated, do not edit manually -->

315 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-dist-tag.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-dist-tag

3 section: 1

4 description: Modify package distribution tags

5 -redirect_from:

6 - - /cli/dist-tag

7 - - /cli/dist-tag.html

8 - - /cli/commands/dist-tag

9 - - /cli-commands/dist-tag

10 - - /cli-commands/dist-tag.html

11 - - /cli-commands/npm-dist-tag

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-dist-tag.md

8 ---

9

@@ -116,8 +109,8 @@ Valid values for the `workspace` config are either:

109

110 * Workspace names

111 * Path to a workspace directory

119 -* Path to a parent workspace directory (will result in selecting all

120 - workspaces within that folder)

112 +* Path to a parent workspace directory (will result to selecting all of the

113 + nested workspaces)

114

115 When set for the `npm init` command, this may be set to the folder of a

116 workspace which does not yet exist, to create the folder and set it up as a

@@ -130,35 +123,13 @@ This value is not exported to the environment for child processes.

123

124 #### `workspaces`

125

133 -* Default: null

134 -* Type: null or Boolean

135 -

136 -Set to true to run the command in the context of **all** configured

137 -workspaces.

138 -

139 -Explicitly setting this to false will cause commands like `install` to

140 -ignore workspaces altogether. When not set explicitly:

141 -

142 -- Commands that operate on the `node_modules` tree (install, update, etc.)

143 -will link workspaces into the `node_modules` folder. - Commands that do

144 -other things (test, exec, publish, etc.) will operate on the root project,

145 -_unless_ one or more workspaces are specified in the `workspace` config.

146 -

147 -This value is not exported to the environment for child processes.

148 -

149 -<!-- automatically generated, do not edit manually -->

150 -<!-- see lib/utils/config/definitions.js -->

151 -

152 -#### `include-workspace-root`

153 -

126 * Default: false

127 * Type: Boolean

128

157 -Include the workspace root when workspaces are enabled for a command.

129 +Enable running a command in the context of **all** the configured

130 +workspaces.

131

159 -When false, specifying individual workspaces via the `workspace` config, or

160 -all workspaces via the `workspaces` flag, will cause npm to operate only on

161 -the specified workspaces, and not on the root project.

132 +This value is not exported to the environment for child processes.

133

134 <!-- automatically generated, do not edit manually -->

135 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-docs.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-docs

3 section: 1

4 description: Open documentation for a package in a web browser

5 -redirect_from:

6 - - /cli/docs

7 - - /cli/docs.html

8 - - /cli/commands/docs

9 - - /cli-commands/docs

10 - - /cli-commands/docs.html

11 - - /cli-commands/npm-docs

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-docs.md

8 ---

9

@@ -73,8 +66,8 @@ Valid values for the `workspace` config are either:

66

67 * Workspace names

68 * Path to a workspace directory

76 -* Path to a parent workspace directory (will result in selecting all

77 - workspaces within that folder)

69 +* Path to a parent workspace directory (will result to selecting all of the

70 + nested workspaces)

71

72 When set for the `npm init` command, this may be set to the folder of a

73 workspace which does not yet exist, to create the folder and set it up as a

@@ -87,35 +80,13 @@ This value is not exported to the environment for child processes.

80

81 #### `workspaces`

82

90 -* Default: null

91 -* Type: null or Boolean

92 -

93 -Set to true to run the command in the context of **all** configured

94 -workspaces.

95 -

96 -Explicitly setting this to false will cause commands like `install` to

97 -ignore workspaces altogether. When not set explicitly:

98 -

99 -- Commands that operate on the `node_modules` tree (install, update, etc.)

100 -will link workspaces into the `node_modules` folder. - Commands that do

101 -other things (test, exec, publish, etc.) will operate on the root project,

102 -_unless_ one or more workspaces are specified in the `workspace` config.

103 -

104 -This value is not exported to the environment for child processes.

105 -

106 -<!-- automatically generated, do not edit manually -->

107 -<!-- see lib/utils/config/definitions.js -->

108 -

109 -#### `include-workspace-root`

110 -

83 * Default: false

84 * Type: Boolean

85

114 -Include the workspace root when workspaces are enabled for a command.

86 +Enable running a command in the context of **all** the configured

87 +workspaces.

88

116 -When false, specifying individual workspaces via the `workspace` config, or

117 -all workspaces via the `workspaces` flag, will cause npm to operate only on

118 -the specified workspaces, and not on the root project.

89 +This value is not exported to the environment for child processes.

90

91 <!-- automatically generated, do not edit manually -->

92 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-doctor.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-doctor

3 section: 1

4 description: Check your npm environment

5 -redirect_from:

6 - - /cli/doctor

7 - - /cli/doctor.html

8 - - /cli/commands/doctor

9 - - /cli-commands/doctor

10 - - /cli-commands/doctor.html

11 - - /cli-commands/npm-doctor

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-doctor.md

8 ---

9

content/cli/v7/commands/npm-edit.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-edit

3 section: 1

4 description: Edit an installed package

5 -redirect_from:

6 - - /cli/edit

7 - - /cli/edit.html

8 - - /cli/commands/edit

9 - - /cli-commands/edit

10 - - /cli-commands/edit.html

11 - - /cli-commands/npm-edit

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-edit.md

8 ---

9

content/cli/v7/commands/npm-exec.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-exec

3 section: 1

4 description: Run a command from a local or remote npm package

5 -redirect_from:

6 - - /cli/exec

7 - - /cli/exec.html

8 - - /cli/commands/exec

9 - - /cli-commands/exec

10 - - /cli-commands/exec.html

11 - - /cli-commands/npm-exec

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-exec.md

8 ---

9

@@ -174,8 +167,8 @@ Valid values for the `workspace` config are either:

167

168 * Workspace names

169 * Path to a workspace directory

177 -* Path to a parent workspace directory (will result in selecting all

178 - workspaces within that folder)

170 +* Path to a parent workspace directory (will result to selecting all of the

171 + nested workspaces)

172

173 When set for the `npm init` command, this may be set to the folder of a

174 workspace which does not yet exist, to create the folder and set it up as a

@@ -188,35 +181,13 @@ This value is not exported to the environment for child processes.

181

182 #### `workspaces`

183

191 -* Default: null

192 -* Type: null or Boolean

193 -

194 -Set to true to run the command in the context of **all** configured

195 -workspaces.

196 -

197 -Explicitly setting this to false will cause commands like `install` to

198 -ignore workspaces altogether. When not set explicitly:

199 -

200 -- Commands that operate on the `node_modules` tree (install, update, etc.)

201 -will link workspaces into the `node_modules` folder. - Commands that do

202 -other things (test, exec, publish, etc.) will operate on the root project,

203 -_unless_ one or more workspaces are specified in the `workspace` config.

204 -

205 -This value is not exported to the environment for child processes.

206 -

207 -<!-- automatically generated, do not edit manually -->

208 -<!-- see lib/utils/config/definitions.js -->

209 -

210 -#### `include-workspace-root`

211 -

184 * Default: false

185 * Type: Boolean

186

215 -Include the workspace root when workspaces are enabled for a command.

187 +Enable running a command in the context of **all** the configured

188 +workspaces.

189

217 -When false, specifying individual workspaces via the `workspace` config, or

218 -all workspaces via the `workspaces` flag, will cause npm to operate only on

219 -the specified workspaces, and not on the root project.

190 +This value is not exported to the environment for child processes.

191

192 <!-- automatically generated, do not edit manually -->

193 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-explain.md

+3 -10

@@ -2,15 +2,8 @@

2 title: npm-explain

3 section: 1

4 description: Explain installed packages

5 -redirect_from:

6 - - /cli/explain

7 - - /cli/explain.html

8 - - /cli/commands/explain

9 - - /cli-commands/explain

10 - - /cli-commands/explain.html

11 - - /cli-commands/npm-explain

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-explain.md

8 ---

9

@@ -95,8 +88,8 @@ Valid values for the `workspace` config are either:

88

89 * Workspace names

90 * Path to a workspace directory

98 -* Path to a parent workspace directory (will result in selecting all

99 - workspaces within that folder)

91 +* Path to a parent workspace directory (will result to selecting all of the

92 + nested workspaces)

93

94 When set for the `npm init` command, this may be set to the folder of a

95 workspace which does not yet exist, to create the folder and set it up as a

content/cli/v7/commands/npm-explore.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-explore

3 section: 1

4 description: Browse an installed package

5 -redirect_from:

6 - - /cli/explore

7 - - /cli/explore.html

8 - - /cli/commands/explore

9 - - /cli-commands/explore

10 - - /cli-commands/explore.html

11 - - /cli-commands/npm-explore

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-explore.md

8 ---

9

content/cli/v7/commands/npm-find-dupes.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-find-dupes

3 section: 1

4 description: Find duplication in the package tree

5 -redirect_from:

6 - - /cli/find-dupes

7 - - /cli/find-dupes.html

8 - - /cli/commands/find-dupes

9 - - /cli-commands/find-dupes

10 - - /cli-commands/find-dupes.html

11 - - /cli-commands/npm-find-dupes

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-find-dupes.md

8 ---

9

@@ -184,8 +177,8 @@ Valid values for the `workspace` config are either:

177

178 * Workspace names

179 * Path to a workspace directory

187 -* Path to a parent workspace directory (will result in selecting all

188 - workspaces within that folder)

180 +* Path to a parent workspace directory (will result to selecting all of the

181 + nested workspaces)

182

183 When set for the `npm init` command, this may be set to the folder of a

184 workspace which does not yet exist, to create the folder and set it up as a

@@ -198,35 +191,13 @@ This value is not exported to the environment for child processes.

191

192 #### `workspaces`

193

201 -* Default: null

202 -* Type: null or Boolean

203 -

204 -Set to true to run the command in the context of **all** configured

205 -workspaces.

206 -

207 -Explicitly setting this to false will cause commands like `install` to

208 -ignore workspaces altogether. When not set explicitly:

209 -

210 -- Commands that operate on the `node_modules` tree (install, update, etc.)

211 -will link workspaces into the `node_modules` folder. - Commands that do

212 -other things (test, exec, publish, etc.) will operate on the root project,

213 -_unless_ one or more workspaces are specified in the `workspace` config.

214 -

215 -This value is not exported to the environment for child processes.

216 -

217 -<!-- automatically generated, do not edit manually -->

218 -<!-- see lib/utils/config/definitions.js -->

219 -

220 -#### `include-workspace-root`

221 -

194 * Default: false

195 * Type: Boolean

196

225 -Include the workspace root when workspaces are enabled for a command.

197 +Enable running a command in the context of **all** the configured

198 +workspaces.

199

227 -When false, specifying individual workspaces via the `workspace` config, or

228 -all workspaces via the `workspaces` flag, will cause npm to operate only on

229 -the specified workspaces, and not on the root project.

200 +This value is not exported to the environment for child processes.

201

202 <!-- automatically generated, do not edit manually -->

203 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-fund.md

+3 -10

@@ -2,15 +2,8 @@

2 title: npm-fund

3 section: 1

4 description: Retrieve funding information

5 -redirect_from:

6 - - /cli/fund

7 - - /cli/fund.html

8 - - /cli/commands/fund

9 - - /cli-commands/fund

10 - - /cli-commands/fund.html

11 - - /cli-commands/npm-fund

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-fund.md

8 ---

9

@@ -132,8 +125,8 @@ Valid values for the `workspace` config are either:

125

126 * Workspace names

127 * Path to a workspace directory

135 -* Path to a parent workspace directory (will result in selecting all

136 - workspaces within that folder)

128 +* Path to a parent workspace directory (will result to selecting all of the

129 + nested workspaces)

130

131 When set for the `npm init` command, this may be set to the folder of a

132 workspace which does not yet exist, to create the folder and set it up as a

content/cli/v7/commands/npm-help-search.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-help-search

3 section: 1

4 description: Search npm help documentation

5 -redirect_from:

6 - - /cli/help-search

7 - - /cli/help-search.html

8 - - /cli/commands/help-search

9 - - /cli-commands/help-search

10 - - /cli-commands/help-search.html

11 - - /cli-commands/npm-help-search

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-help-search.md

8 ---

9

content/cli/v7/commands/npm-help.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-help

3 section: 1

4 description: Get help on npm

5 -redirect_from:

6 - - /cli/help

7 - - /cli/help.html

8 - - /cli/commands/help

9 - - /cli-commands/help

10 - - /cli-commands/help.html

11 - - /cli-commands/npm-help

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-help.md

8 ---

9

content/cli/v7/commands/npm-hook.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-hook

3 section: 1

4 description: Manage registry hooks

5 -redirect_from:

6 - - /cli/hook

7 - - /cli/hook.html

8 - - /cli/commands/hook

9 - - /cli-commands/hook

10 - - /cli-commands/hook.html

11 - - /cli-commands/npm-hook

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-hook.md

8 ---

9

content/cli/v7/commands/npm-init.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-init

3 section: 1

4 description: Create a package.json file

5 -redirect_from:

6 - - /cli/init

7 - - /cli/init.html

8 - - /cli/commands/init

9 - - /cli-commands/init

10 - - /cli-commands/init.html

11 - - /cli-commands/npm-init

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-init.md

8 ---

9

@@ -210,8 +203,8 @@ Valid values for the `workspace` config are either:

203

204 * Workspace names

205 * Path to a workspace directory

213 -* Path to a parent workspace directory (will result in selecting all

214 - workspaces within that folder)

206 +* Path to a parent workspace directory (will result to selecting all of the

207 + nested workspaces)

208

209 When set for the `npm init` command, this may be set to the folder of a

210 workspace which does not yet exist, to create the folder and set it up as a

@@ -224,35 +217,13 @@ This value is not exported to the environment for child processes.

217

218 #### `workspaces`

219

227 -* Default: null

228 -* Type: null or Boolean

229 -

230 -Set to true to run the command in the context of **all** configured

231 -workspaces.

232 -

233 -Explicitly setting this to false will cause commands like `install` to

234 -ignore workspaces altogether. When not set explicitly:

235 -

236 -- Commands that operate on the `node_modules` tree (install, update, etc.)

237 -will link workspaces into the `node_modules` folder. - Commands that do

238 -other things (test, exec, publish, etc.) will operate on the root project,

239 -_unless_ one or more workspaces are specified in the `workspace` config.

240 -

241 -This value is not exported to the environment for child processes.

242 -

243 -<!-- automatically generated, do not edit manually -->

244 -<!-- see lib/utils/config/definitions.js -->

245 -

246 -#### `include-workspace-root`

247 -

220 * Default: false

221 * Type: Boolean

222

251 -Include the workspace root when workspaces are enabled for a command.

223 +Enable running a command in the context of **all** the configured

224 +workspaces.

225

253 -When false, specifying individual workspaces via the `workspace` config, or

254 -all workspaces via the `workspaces` flag, will cause npm to operate only on

255 -the specified workspaces, and not on the root project.

226 +This value is not exported to the environment for child processes.

227

228 <!-- automatically generated, do not edit manually -->

229 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-install-ci-test.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-install-ci-test

3 section: 1

4 description: Install a project with a clean slate and run tests

5 -redirect_from:

6 - - /cli/install-ci-test

7 - - /cli/install-ci-test.html

8 - - /cli/commands/install-ci-test

9 - - /cli-commands/install-ci-test

10 - - /cli-commands/install-ci-test.html

11 - - /cli-commands/npm-install-ci-test

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-install-ci-test.md

8 ---

9

content/cli/v7/commands/npm-install-test.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-install-test

3 section: 1

4 description: Install package(s) and run tests

5 -redirect_from:

6 - - /cli/install-test

7 - - /cli/install-test.html

8 - - /cli/commands/install-test

9 - - /cli-commands/install-test

10 - - /cli-commands/install-test.html

11 - - /cli-commands/npm-install-test

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-install-test.md

8 ---

9

@@ -251,8 +244,8 @@ Valid values for the `workspace` config are either:

244

245 * Workspace names

246 * Path to a workspace directory

254 -* Path to a parent workspace directory (will result in selecting all

255 - workspaces within that folder)

247 +* Path to a parent workspace directory (will result to selecting all of the

248 + nested workspaces)

249

250 When set for the `npm init` command, this may be set to the folder of a

251 workspace which does not yet exist, to create the folder and set it up as a

@@ -265,35 +258,13 @@ This value is not exported to the environment for child processes.

258

259 #### `workspaces`

260

268 -* Default: null

269 -* Type: null or Boolean

270 -

271 -Set to true to run the command in the context of **all** configured

272 -workspaces.

273 -

274 -Explicitly setting this to false will cause commands like `install` to

275 -ignore workspaces altogether. When not set explicitly:

276 -

277 -- Commands that operate on the `node_modules` tree (install, update, etc.)

278 -will link workspaces into the `node_modules` folder. - Commands that do

279 -other things (test, exec, publish, etc.) will operate on the root project,

280 -_unless_ one or more workspaces are specified in the `workspace` config.

281 -

282 -This value is not exported to the environment for child processes.

283 -

284 -<!-- automatically generated, do not edit manually -->

285 -<!-- see lib/utils/config/definitions.js -->

286 -

287 -#### `include-workspace-root`

288 -

261 * Default: false

262 * Type: Boolean

263

292 -Include the workspace root when workspaces are enabled for a command.

264 +Enable running a command in the context of **all** the configured

265 +workspaces.

266

294 -When false, specifying individual workspaces via the `workspace` config, or

295 -all workspaces via the `workspaces` flag, will cause npm to operate only on

296 -the specified workspaces, and not on the root project.

267 +This value is not exported to the environment for child processes.

268

269 <!-- automatically generated, do not edit manually -->

270 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-install.md

+6 -36

@@ -2,16 +2,8 @@

2 title: npm-install

3 section: 1

4 description: Install a package

5 -redirect_from:

6 - - /cli/install

7 - - /cli/install.html

8 - - /cli/commands/install

9 - - /cli-commands/install

10 - - /cli-commands/install.html

11 - - /cli-commands/npm-install

12 - - /cli-documentation/install

5 github_repo: npm/cli

14 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-install.md

8 ---

9

@@ -636,8 +628,8 @@ Valid values for the `workspace` config are either:

628

629 * Workspace names

630 * Path to a workspace directory

639 -* Path to a parent workspace directory (will result in selecting all

640 - workspaces within that folder)

631 +* Path to a parent workspace directory (will result to selecting all of the

632 + nested workspaces)

633

634 When set for the `npm init` command, this may be set to the folder of a

635 workspace which does not yet exist, to create the folder and set it up as a

@@ -650,35 +642,13 @@ This value is not exported to the environment for child processes.

642

643 #### `workspaces`

644

653 -* Default: null

654 -* Type: null or Boolean

655 -

656 -Set to true to run the command in the context of **all** configured

657 -workspaces.

658 -

659 -Explicitly setting this to false will cause commands like `install` to

660 -ignore workspaces altogether. When not set explicitly:

661 -

662 -- Commands that operate on the `node_modules` tree (install, update, etc.)

663 -will link workspaces into the `node_modules` folder. - Commands that do

664 -other things (test, exec, publish, etc.) will operate on the root project,

665 -_unless_ one or more workspaces are specified in the `workspace` config.

666 -

667 -This value is not exported to the environment for child processes.

668 -

669 -<!-- automatically generated, do not edit manually -->

670 -<!-- see lib/utils/config/definitions.js -->

671 -

672 -#### `include-workspace-root`

673 -

645 * Default: false

646 * Type: Boolean

647

677 -Include the workspace root when workspaces are enabled for a command.

648 +Enable running a command in the context of **all** the configured

649 +workspaces.

650

679 -When false, specifying individual workspaces via the `workspace` config, or

680 -all workspaces via the `workspaces` flag, will cause npm to operate only on

681 -the specified workspaces, and not on the root project.

651 +This value is not exported to the environment for child processes.

652

653 <!-- automatically generated, do not edit manually -->

654 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-link.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-link

3 section: 1

4 description: Symlink a package folder

5 -redirect_from:

6 - - /cli/link

7 - - /cli/link.html

8 - - /cli/commands/link

9 - - /cli-commands/link

10 - - /cli-commands/link.html

11 - - /cli-commands/npm-link

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-link.md

8 ---

9

@@ -335,8 +328,8 @@ Valid values for the `workspace` config are either:

328

329 * Workspace names

330 * Path to a workspace directory

338 -* Path to a parent workspace directory (will result in selecting all

339 - workspaces within that folder)

331 +* Path to a parent workspace directory (will result to selecting all of the

332 + nested workspaces)

333

334 When set for the `npm init` command, this may be set to the folder of a

335 workspace which does not yet exist, to create the folder and set it up as a

@@ -349,35 +342,13 @@ This value is not exported to the environment for child processes.

342

343 #### `workspaces`

344

352 -* Default: null

353 -* Type: null or Boolean

354 -

355 -Set to true to run the command in the context of **all** configured

356 -workspaces.

357 -

358 -Explicitly setting this to false will cause commands like `install` to

359 -ignore workspaces altogether. When not set explicitly:

360 -

361 -- Commands that operate on the `node_modules` tree (install, update, etc.)

362 -will link workspaces into the `node_modules` folder. - Commands that do

363 -other things (test, exec, publish, etc.) will operate on the root project,

364 -_unless_ one or more workspaces are specified in the `workspace` config.

365 -

366 -This value is not exported to the environment for child processes.

367 -

368 -<!-- automatically generated, do not edit manually -->

369 -<!-- see lib/utils/config/definitions.js -->

370 -

371 -#### `include-workspace-root`

372 -

345 * Default: false

346 * Type: Boolean

347

376 -Include the workspace root when workspaces are enabled for a command.

348 +Enable running a command in the context of **all** the configured

349 +workspaces.

350

378 -When false, specifying individual workspaces via the `workspace` config, or

379 -all workspaces via the `workspaces` flag, will cause npm to operate only on

380 -the specified workspaces, and not on the root project.

351 +This value is not exported to the environment for child processes.

352

353 <!-- automatically generated, do not edit manually -->

354 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-logout.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-logout

3 section: 1

4 description: Log out of the registry

5 -redirect_from:

6 - - /cli/logout

7 - - /cli/logout.html

8 - - /cli/commands/logout

9 - - /cli-commands/logout

10 - - /cli-commands/logout.html

11 - - /cli-commands/npm-logout

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-logout.md

8 ---

9

content/cli/v7/commands/npm-ls.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-ls

3 section: 1

4 description: List installed packages

5 -redirect_from:

6 - - /cli/ls

7 - - /cli/ls.html

8 - - /cli/commands/ls

9 - - /cli-commands/ls

10 - - /cli-commands/ls.html

11 - - /cli-commands/npm-ls

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-ls.md

8 ---

9

@@ -237,8 +230,8 @@ Valid values for the `workspace` config are either:

230

231 * Workspace names

232 * Path to a workspace directory

240 -* Path to a parent workspace directory (will result in selecting all

241 - workspaces within that folder)

233 +* Path to a parent workspace directory (will result to selecting all of the

234 + nested workspaces)

235

236 When set for the `npm init` command, this may be set to the folder of a

237 workspace which does not yet exist, to create the folder and set it up as a

@@ -251,35 +244,13 @@ This value is not exported to the environment for child processes.

244

245 #### `workspaces`

246

254 -* Default: null

255 -* Type: null or Boolean

256 -

257 -Set to true to run the command in the context of **all** configured

258 -workspaces.

259 -

260 -Explicitly setting this to false will cause commands like `install` to

261 -ignore workspaces altogether. When not set explicitly:

262 -

263 -- Commands that operate on the `node_modules` tree (install, update, etc.)

264 -will link workspaces into the `node_modules` folder. - Commands that do

265 -other things (test, exec, publish, etc.) will operate on the root project,

266 -_unless_ one or more workspaces are specified in the `workspace` config.

267 -

268 -This value is not exported to the environment for child processes.

269 -

270 -<!-- automatically generated, do not edit manually -->

271 -<!-- see lib/utils/config/definitions.js -->

272 -

273 -#### `include-workspace-root`

274 -

247 * Default: false

248 * Type: Boolean

249

278 -Include the workspace root when workspaces are enabled for a command.

250 +Enable running a command in the context of **all** the configured

251 +workspaces.

252

280 -When false, specifying individual workspaces via the `workspace` config, or

281 -all workspaces via the `workspaces` flag, will cause npm to operate only on

282 -the specified workspaces, and not on the root project.

253 +This value is not exported to the environment for child processes.

254

255 <!-- automatically generated, do not edit manually -->

256 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-org.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-org

3 section: 1

4 description: Manage orgs

5 -redirect_from:

6 - - /cli/org

7 - - /cli/org.html

8 - - /cli/commands/org

9 - - /cli-commands/org

10 - - /cli-commands/org.html

11 - - /cli-commands/npm-org

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-org.md

8 ---

9

content/cli/v7/commands/npm-outdated.md

+3 -10

@@ -2,15 +2,8 @@

2 title: npm-outdated

3 section: 1

4 description: Check for outdated packages

5 -redirect_from:

6 - - /cli/outdated

7 - - /cli/outdated.html

8 - - /cli/commands/outdated

9 - - /cli-commands/outdated

10 - - /cli-commands/outdated.html

11 - - /cli-commands/npm-outdated

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-outdated.md

8 ---

9

@@ -177,8 +170,8 @@ Valid values for the `workspace` config are either:

170

171 * Workspace names

172 * Path to a workspace directory

180 -* Path to a parent workspace directory (will result in selecting all

181 - workspaces within that folder)

173 +* Path to a parent workspace directory (will result to selecting all of the

174 + nested workspaces)

175

176 When set for the `npm init` command, this may be set to the folder of a

177 workspace which does not yet exist, to create the folder and set it up as a

content/cli/v7/commands/npm-owner.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-owner

3 section: 1

4 description: Manage package owners

5 -redirect_from:

6 - - /cli/owner

7 - - /cli/owner.html

8 - - /cli/commands/owner

9 - - /cli-commands/owner

10 - - /cli-commands/owner.html

11 - - /cli-commands/npm-owner

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-owner.md

8 ---

9

content/cli/v7/commands/npm-pack.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-pack

3 section: 1

4 description: Create a tarball from a package

5 -redirect_from:

6 - - /cli/pack

7 - - /cli/pack.html

8 - - /cli/commands/pack

9 - - /cli-commands/pack

10 - - /cli-commands/pack.html

11 - - /cli-commands/npm-pack

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-pack.md

8 ---

9

@@ -79,8 +72,8 @@ Valid values for the `workspace` config are either:

72

73 * Workspace names

74 * Path to a workspace directory

82 -* Path to a parent workspace directory (will result in selecting all

83 - workspaces within that folder)

75 +* Path to a parent workspace directory (will result to selecting all of the

76 + nested workspaces)

77

78 When set for the `npm init` command, this may be set to the folder of a

79 workspace which does not yet exist, to create the folder and set it up as a

@@ -93,35 +86,13 @@ This value is not exported to the environment for child processes.

86

87 #### `workspaces`

88

96 -* Default: null

97 -* Type: null or Boolean

98 -

99 -Set to true to run the command in the context of **all** configured

100 -workspaces.

101 -

102 -Explicitly setting this to false will cause commands like `install` to

103 -ignore workspaces altogether. When not set explicitly:

104 -

105 -- Commands that operate on the `node_modules` tree (install, update, etc.)

106 -will link workspaces into the `node_modules` folder. - Commands that do

107 -other things (test, exec, publish, etc.) will operate on the root project,

108 -_unless_ one or more workspaces are specified in the `workspace` config.

109 -

110 -This value is not exported to the environment for child processes.

111 -

112 -<!-- automatically generated, do not edit manually -->

113 -<!-- see lib/utils/config/definitions.js -->

114 -

115 -#### `include-workspace-root`

116 -

89 * Default: false

90 * Type: Boolean

91

120 -Include the workspace root when workspaces are enabled for a command.

92 +Enable running a command in the context of **all** the configured

93 +workspaces.

94

122 -When false, specifying individual workspaces via the `workspace` config, or

123 -all workspaces via the `workspaces` flag, will cause npm to operate only on

124 -the specified workspaces, and not on the root project.

95 +This value is not exported to the environment for child processes.

96

97 <!-- automatically generated, do not edit manually -->

98 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-ping.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-ping

3 section: 1

4 description: Ping npm registry

5 -redirect_from:

6 - - /cli/ping

7 - - /cli/ping.html

8 - - /cli/commands/ping

9 - - /cli-commands/ping

10 - - /cli-commands/ping.html

11 - - /cli-commands/npm-ping

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-ping.md

8 ---

9

content/cli/v7/commands/npm-pkg.md

+6 -21

@@ -2,15 +2,8 @@

2 title: npm-pkg

3 section: 1

4 description: Manages your package.json

5 -redirect_from:

6 - - /cli/pkg

7 - - /cli/pkg.html

8 - - /cli/commands/pkg

9 - - /cli-commands/pkg

10 - - /cli-commands/pkg.html

11 - - /cli-commands/npm-pkg

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-pkg.md

8 ---

9

@@ -233,8 +226,8 @@ Valid values for the `workspace` config are either:

226

227 * Workspace names

228 * Path to a workspace directory

236 -* Path to a parent workspace directory (will result in selecting all

237 - workspaces within that folder)

229 +* Path to a parent workspace directory (will result to selecting all of the

230 + nested workspaces)

231

232 When set for the `npm init` command, this may be set to the folder of a

233 workspace which does not yet exist, to create the folder and set it up as a

@@ -247,20 +240,12 @@ This value is not exported to the environment for child processes.

240

241 #### `workspaces`

242

250 -* Default: null

251 -* Type: null or Boolean

243 +* Default: false

244 +* Type: Boolean

245

253 -Set to true to run the command in the context of **all** configured

246 +Enable running a command in the context of **all** the configured

247 workspaces.

248

256 -Explicitly setting this to false will cause commands like `install` to

257 -ignore workspaces altogether. When not set explicitly:

258 -

259 -- Commands that operate on the `node_modules` tree (install, update, etc.)

260 -will link workspaces into the `node_modules` folder. - Commands that do

261 -other things (test, exec, publish, etc.) will operate on the root project,

262 -_unless_ one or more workspaces are specified in the `workspace` config.

263 -

249 This value is not exported to the environment for child processes.

250

251 <!-- automatically generated, do not edit manually -->

content/cli/v7/commands/npm-prefix.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-prefix

3 section: 1

4 description: Display prefix

5 -redirect_from:

6 - - /cli/prefix

7 - - /cli/prefix.html

8 - - /cli/commands/prefix

9 - - /cli-commands/prefix

10 - - /cli-commands/prefix.html

11 - - /cli-commands/npm-prefix

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-prefix.md

8 ---

9

content/cli/v7/commands/npm-profile.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-profile

3 section: 1

4 description: Change settings on your registry profile

5 -redirect_from:

6 - - /cli/profile

7 - - /cli/profile.html

8 - - /cli/commands/profile

9 - - /cli-commands/profile

10 - - /cli-commands/profile.html

11 - - /cli-commands/npm-profile

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-profile.md

8 ---

9

content/cli/v7/commands/npm-prune.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-prune

3 section: 1

4 description: Remove extraneous packages

5 -redirect_from:

6 - - /cli/prune

7 - - /cli/prune.html

8 - - /cli/commands/prune

9 - - /cli-commands/prune

10 - - /cli-commands/prune.html

11 - - /cli-commands/npm-prune

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-prune.md

8 ---

9

@@ -113,8 +106,8 @@ Valid values for the `workspace` config are either:

106

107 * Workspace names

108 * Path to a workspace directory

116 -* Path to a parent workspace directory (will result in selecting all

117 - workspaces within that folder)

109 +* Path to a parent workspace directory (will result to selecting all of the

110 + nested workspaces)

111

112 When set for the `npm init` command, this may be set to the folder of a

113 workspace which does not yet exist, to create the folder and set it up as a

@@ -127,35 +120,13 @@ This value is not exported to the environment for child processes.

120

121 #### `workspaces`

122

130 -* Default: null

131 -* Type: null or Boolean

132 -

133 -Set to true to run the command in the context of **all** configured

134 -workspaces.

135 -

136 -Explicitly setting this to false will cause commands like `install` to

137 -ignore workspaces altogether. When not set explicitly:

138 -

139 -- Commands that operate on the `node_modules` tree (install, update, etc.)

140 -will link workspaces into the `node_modules` folder. - Commands that do

141 -other things (test, exec, publish, etc.) will operate on the root project,

142 -_unless_ one or more workspaces are specified in the `workspace` config.

143 -

144 -This value is not exported to the environment for child processes.

145 -

146 -<!-- automatically generated, do not edit manually -->

147 -<!-- see lib/utils/config/definitions.js -->

148 -

149 -#### `include-workspace-root`

150 -

123 * Default: false

124 * Type: Boolean

125

154 -Include the workspace root when workspaces are enabled for a command.

126 +Enable running a command in the context of **all** the configured

127 +workspaces.

128

156 -When false, specifying individual workspaces via the `workspace` config, or

157 -all workspaces via the `workspaces` flag, will cause npm to operate only on

158 -the specified workspaces, and not on the root project.

129 +This value is not exported to the environment for child processes.

130

131 <!-- automatically generated, do not edit manually -->

132 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-publish.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-publish

3 section: 1

4 description: Publish a package

5 -redirect_from:

6 - - /cli/publish

7 - - /cli/publish.html

8 - - /cli/commands/publish

9 - - /cli-commands/publish

10 - - /cli-commands/publish.html

11 - - /cli-commands/npm-publish

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-publish.md

8 ---

9

@@ -198,8 +191,8 @@ Valid values for the `workspace` config are either:

191

192 * Workspace names

193 * Path to a workspace directory

201 -* Path to a parent workspace directory (will result in selecting all

202 - workspaces within that folder)

194 +* Path to a parent workspace directory (will result to selecting all of the

195 + nested workspaces)

196

197 When set for the `npm init` command, this may be set to the folder of a

198 workspace which does not yet exist, to create the folder and set it up as a

@@ -212,35 +205,13 @@ This value is not exported to the environment for child processes.

205

206 #### `workspaces`

207

215 -* Default: null

216 -* Type: null or Boolean

217 -

218 -Set to true to run the command in the context of **all** configured

219 -workspaces.

220 -

221 -Explicitly setting this to false will cause commands like `install` to

222 -ignore workspaces altogether. When not set explicitly:

223 -

224 -- Commands that operate on the `node_modules` tree (install, update, etc.)

225 -will link workspaces into the `node_modules` folder. - Commands that do

226 -other things (test, exec, publish, etc.) will operate on the root project,

227 -_unless_ one or more workspaces are specified in the `workspace` config.

228 -

229 -This value is not exported to the environment for child processes.

230 -

231 -<!-- automatically generated, do not edit manually -->

232 -<!-- see lib/utils/config/definitions.js -->

233 -

234 -#### `include-workspace-root`

235 -

208 * Default: false

209 * Type: Boolean

210

239 -Include the workspace root when workspaces are enabled for a command.

211 +Enable running a command in the context of **all** the configured

212 +workspaces.

213

241 -When false, specifying individual workspaces via the `workspace` config, or

242 -all workspaces via the `workspaces` flag, will cause npm to operate only on

243 -the specified workspaces, and not on the root project.

214 +This value is not exported to the environment for child processes.

215

216 <!-- automatically generated, do not edit manually -->

217 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-rebuild.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-rebuild

3 section: 1

4 description: Rebuild a package

5 -redirect_from:

6 - - /cli/rebuild

7 - - /cli/rebuild.html

8 - - /cli/commands/rebuild

9 - - /cli-commands/rebuild

10 - - /cli-commands/rebuild.html

11 - - /cli-commands/npm-rebuild

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-rebuild.md

8 ---

9

@@ -99,8 +92,8 @@ Valid values for the `workspace` config are either:

92

93 * Workspace names

94 * Path to a workspace directory

102 -* Path to a parent workspace directory (will result in selecting all

103 - workspaces within that folder)

95 +* Path to a parent workspace directory (will result to selecting all of the

96 + nested workspaces)

97

98 When set for the `npm init` command, this may be set to the folder of a

99 workspace which does not yet exist, to create the folder and set it up as a

@@ -113,35 +106,13 @@ This value is not exported to the environment for child processes.

106

107 #### `workspaces`

108

116 -* Default: null

117 -* Type: null or Boolean

118 -

119 -Set to true to run the command in the context of **all** configured

120 -workspaces.

121 -

122 -Explicitly setting this to false will cause commands like `install` to

123 -ignore workspaces altogether. When not set explicitly:

124 -

125 -- Commands that operate on the `node_modules` tree (install, update, etc.)

126 -will link workspaces into the `node_modules` folder. - Commands that do

127 -other things (test, exec, publish, etc.) will operate on the root project,

128 -_unless_ one or more workspaces are specified in the `workspace` config.

129 -

130 -This value is not exported to the environment for child processes.

131 -

132 -<!-- automatically generated, do not edit manually -->

133 -<!-- see lib/utils/config/definitions.js -->

134 -

135 -#### `include-workspace-root`

136 -

109 * Default: false

110 * Type: Boolean

111

140 -Include the workspace root when workspaces are enabled for a command.

112 +Enable running a command in the context of **all** the configured

113 +workspaces.

114

142 -When false, specifying individual workspaces via the `workspace` config, or

143 -all workspaces via the `workspaces` flag, will cause npm to operate only on

144 -the specified workspaces, and not on the root project.

115 +This value is not exported to the environment for child processes.

116

117 <!-- automatically generated, do not edit manually -->

118 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-repo.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-repo

3 section: 1

4 description: Open package repository page in the browser

5 -redirect_from:

6 - - /cli/repo

7 - - /cli/repo.html

8 - - /cli/commands/repo

9 - - /cli-commands/repo

10 - - /cli-commands/repo.html

11 - - /cli-commands/npm-repo

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-repo.md

8 ---

9

@@ -60,8 +53,8 @@ Valid values for the `workspace` config are either:

53

54 * Workspace names

55 * Path to a workspace directory

63 -* Path to a parent workspace directory (will result in selecting all

64 - workspaces within that folder)

56 +* Path to a parent workspace directory (will result to selecting all of the

57 + nested workspaces)

58

59 When set for the `npm init` command, this may be set to the folder of a

60 workspace which does not yet exist, to create the folder and set it up as a

@@ -74,35 +67,13 @@ This value is not exported to the environment for child processes.

67

68 #### `workspaces`

69

77 -* Default: null

78 -* Type: null or Boolean

79 -

80 -Set to true to run the command in the context of **all** configured

81 -workspaces.

82 -

83 -Explicitly setting this to false will cause commands like `install` to

84 -ignore workspaces altogether. When not set explicitly:

85 -

86 -- Commands that operate on the `node_modules` tree (install, update, etc.)

87 -will link workspaces into the `node_modules` folder. - Commands that do

88 -other things (test, exec, publish, etc.) will operate on the root project,

89 -_unless_ one or more workspaces are specified in the `workspace` config.

90 -

91 -This value is not exported to the environment for child processes.

92 -

93 -<!-- automatically generated, do not edit manually -->

94 -<!-- see lib/utils/config/definitions.js -->

95 -

96 -#### `include-workspace-root`

97 -

70 * Default: false

71 * Type: Boolean

72

101 -Include the workspace root when workspaces are enabled for a command.

73 +Enable running a command in the context of **all** the configured

74 +workspaces.

75

103 -When false, specifying individual workspaces via the `workspace` config, or

104 -all workspaces via the `workspaces` flag, will cause npm to operate only on

105 -the specified workspaces, and not on the root project.

76 +This value is not exported to the environment for child processes.

77

78 <!-- automatically generated, do not edit manually -->

79 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-restart.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-restart

3 section: 1

4 description: Restart a package

5 -redirect_from:

6 - - /cli/restart

7 - - /cli/restart.html

8 - - /cli/commands/restart

9 - - /cli-commands/restart

10 - - /cli-commands/restart.html

11 - - /cli-commands/npm-restart

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-restart.md

8 ---

9

content/cli/v7/commands/npm-root.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-root

3 section: 1

4 description: Display npm root

5 -redirect_from:

6 - - /cli/root

7 - - /cli/root.html

8 - - /cli/commands/root

9 - - /cli-commands/root

10 - - /cli-commands/root.html

11 - - /cli-commands/npm-root

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-root.md

8 ---

9

content/cli/v7/commands/npm-run-script.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-run-script

3 section: 1

4 description: Run arbitrary package scripts

5 -redirect_from:

6 - - /cli/run-script

7 - - /cli/run-script.html

8 - - /cli/commands/run-script

9 - - /cli-commands/run-script

10 - - /cli-commands/run-script.html

11 - - /cli-commands/npm-run-script

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-run-script.md

8 ---

9

@@ -162,8 +155,8 @@ Valid values for the `workspace` config are either:

155

156 * Workspace names

157 * Path to a workspace directory

165 -* Path to a parent workspace directory (will result in selecting all

166 - workspaces within that folder)

158 +* Path to a parent workspace directory (will result to selecting all of the

159 + nested workspaces)

160

161 When set for the `npm init` command, this may be set to the folder of a

162 workspace which does not yet exist, to create the folder and set it up as a

@@ -176,35 +169,13 @@ This value is not exported to the environment for child processes.

169

170 #### `workspaces`

171

179 -* Default: null

180 -* Type: null or Boolean

181 -

182 -Set to true to run the command in the context of **all** configured

183 -workspaces.

184 -

185 -Explicitly setting this to false will cause commands like `install` to

186 -ignore workspaces altogether. When not set explicitly:

187 -

188 -- Commands that operate on the `node_modules` tree (install, update, etc.)

189 -will link workspaces into the `node_modules` folder. - Commands that do

190 -other things (test, exec, publish, etc.) will operate on the root project,

191 -_unless_ one or more workspaces are specified in the `workspace` config.

192 -

193 -This value is not exported to the environment for child processes.

194 -

195 -<!-- automatically generated, do not edit manually -->

196 -<!-- see lib/utils/config/definitions.js -->

197 -

198 -#### `include-workspace-root`

199 -

172 * Default: false

173 * Type: Boolean

174

203 -Include the workspace root when workspaces are enabled for a command.

175 +Enable running a command in the context of **all** the configured

176 +workspaces.

177

205 -When false, specifying individual workspaces via the `workspace` config, or

206 -all workspaces via the `workspaces` flag, will cause npm to operate only on

207 -the specified workspaces, and not on the root project.

178 +This value is not exported to the environment for child processes.

179

180 <!-- automatically generated, do not edit manually -->

181 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-search.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-search

3 section: 1

4 description: Search for packages

5 -redirect_from:

6 - - /cli/search

7 - - /cli/search.html

8 - - /cli/commands/search

9 - - /cli-commands/search

10 - - /cli-commands/search.html

11 - - /cli-commands/npm-search

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-search.md

8 ---

9

content/cli/v7/commands/npm-set-script.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-set-script

3 section: 1

4 description: Set tasks in the scripts section of package.json

5 -redirect_from:

6 - - /cli/set-script

7 - - /cli/set-script.html

8 - - /cli/commands/set-script

9 - - /cli-commands/set-script

10 - - /cli-commands/set-script.html

11 - - /cli-commands/npm-set-script

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-set-script.md

8 ---

9

@@ -54,8 +47,8 @@ Valid values for the `workspace` config are either:

47

48 * Workspace names

49 * Path to a workspace directory

57 -* Path to a parent workspace directory (will result in selecting all

58 - workspaces within that folder)

50 +* Path to a parent workspace directory (will result to selecting all of the

51 + nested workspaces)

52

53 When set for the `npm init` command, this may be set to the folder of a

54 workspace which does not yet exist, to create the folder and set it up as a

@@ -68,35 +61,13 @@ This value is not exported to the environment for child processes.

61

62 #### `workspaces`

63

71 -* Default: null

72 -* Type: null or Boolean

73 -

74 -Set to true to run the command in the context of **all** configured

75 -workspaces.

76 -

77 -Explicitly setting this to false will cause commands like `install` to

78 -ignore workspaces altogether. When not set explicitly:

79 -

80 -- Commands that operate on the `node_modules` tree (install, update, etc.)

81 -will link workspaces into the `node_modules` folder. - Commands that do

82 -other things (test, exec, publish, etc.) will operate on the root project,

83 -_unless_ one or more workspaces are specified in the `workspace` config.

84 -

85 -This value is not exported to the environment for child processes.

86 -

87 -<!-- automatically generated, do not edit manually -->

88 -<!-- see lib/utils/config/definitions.js -->

89 -

90 -#### `include-workspace-root`

91 -

64 * Default: false

65 * Type: Boolean

66

95 -Include the workspace root when workspaces are enabled for a command.

67 +Enable running a command in the context of **all** the configured

68 +workspaces.

69

97 -When false, specifying individual workspaces via the `workspace` config, or

98 -all workspaces via the `workspaces` flag, will cause npm to operate only on

99 -the specified workspaces, and not on the root project.

70 +This value is not exported to the environment for child processes.

71

72 <!-- automatically generated, do not edit manually -->

73 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-shrinkwrap.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-shrinkwrap

3 section: 1

4 description: Lock down dependency versions for publication

5 -redirect_from:

6 - - /cli/shrinkwrap

7 - - /cli/shrinkwrap.html

8 - - /cli/commands/shrinkwrap

9 - - /cli-commands/shrinkwrap

10 - - /cli-commands/shrinkwrap.html

11 - - /cli-commands/npm-shrinkwrap

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-shrinkwrap.md

8 ---

9

content/cli/v7/commands/npm-star.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-star

3 section: 1

4 description: Mark your favorite packages

5 -redirect_from:

6 - - /cli/star

7 - - /cli/star.html

8 - - /cli/commands/star

9 - - /cli-commands/star

10 - - /cli-commands/star.html

11 - - /cli-commands/npm-star

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-star.md

8 ---

9

content/cli/v7/commands/npm-stars.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-stars

3 section: 1

4 description: View packages marked as favorites

5 -redirect_from:

6 - - /cli/stars

7 - - /cli/stars.html

8 - - /cli/commands/stars

9 - - /cli-commands/stars

10 - - /cli-commands/stars.html

11 - - /cli-commands/npm-stars

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-stars.md

8 ---

9

content/cli/v7/commands/npm-start.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-start

3 section: 1

4 description: Start a package

5 -redirect_from:

6 - - /cli/start

7 - - /cli/start.html

8 - - /cli/commands/start

9 - - /cli-commands/start

10 - - /cli-commands/start.html

11 - - /cli-commands/npm-start

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-start.md

8 ---

9

content/cli/v7/commands/npm-stop.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-stop

3 section: 1

4 description: Stop a package

5 -redirect_from:

6 - - /cli/stop

7 - - /cli/stop.html

8 - - /cli/commands/stop

9 - - /cli-commands/stop

10 - - /cli-commands/stop.html

11 - - /cli-commands/npm-stop

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-stop.md

8 ---

9

content/cli/v7/commands/npm-team.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-team

3 section: 1

4 description: Manage organization teams and team memberships

5 -redirect_from:

6 - - /cli/team

7 - - /cli/team.html

8 - - /cli/commands/team

9 - - /cli-commands/team

10 - - /cli-commands/team.html

11 - - /cli-commands/npm-team

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-team.md

8 ---

9

content/cli/v7/commands/npm-test.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-test

3 section: 1

4 description: Test a package

5 -redirect_from:

6 - - /cli/test

7 - - /cli/test.html

8 - - /cli/commands/test

9 - - /cli-commands/test

10 - - /cli-commands/test.html

11 - - /cli-commands/npm-test

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-test.md

8 ---

9

content/cli/v7/commands/npm-token.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-token

3 section: 1

4 description: Manage your authentication tokens

5 -redirect_from:

6 - - /cli/token

7 - - /cli/token.html

8 - - /cli/commands/token

9 - - /cli-commands/token

10 - - /cli-commands/token.html

11 - - /cli-commands/npm-token

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-token.md

8 ---

9

content/cli/v7/commands/npm-uninstall.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-uninstall

3 section: 1

4 description: Remove a package

5 -redirect_from:

6 - - /cli/uninstall

7 - - /cli/uninstall.html

8 - - /cli/commands/uninstall

9 - - /cli-commands/uninstall

10 - - /cli-commands/uninstall.html

11 - - /cli-commands/npm-uninstall

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-uninstall.md

8 ---

9

@@ -95,8 +88,8 @@ Valid values for the `workspace` config are either:

88

89 * Workspace names

90 * Path to a workspace directory

98 -* Path to a parent workspace directory (will result in selecting all

99 - workspaces within that folder)

91 +* Path to a parent workspace directory (will result to selecting all of the

92 + nested workspaces)

93

94 When set for the `npm init` command, this may be set to the folder of a

95 workspace which does not yet exist, to create the folder and set it up as a

@@ -109,35 +102,13 @@ This value is not exported to the environment for child processes.

102

103 #### `workspaces`

104

112 -* Default: null

113 -* Type: null or Boolean

114 -

115 -Set to true to run the command in the context of **all** configured

116 -workspaces.

117 -

118 -Explicitly setting this to false will cause commands like `install` to

119 -ignore workspaces altogether. When not set explicitly:

120 -

121 -- Commands that operate on the `node_modules` tree (install, update, etc.)

122 -will link workspaces into the `node_modules` folder. - Commands that do

123 -other things (test, exec, publish, etc.) will operate on the root project,

124 -_unless_ one or more workspaces are specified in the `workspace` config.

125 -

126 -This value is not exported to the environment for child processes.

127 -

128 -<!-- automatically generated, do not edit manually -->

129 -<!-- see lib/utils/config/definitions.js -->

130 -

131 -#### `include-workspace-root`

132 -

105 * Default: false

106 * Type: Boolean

107

136 -Include the workspace root when workspaces are enabled for a command.

108 +Enable running a command in the context of **all** the configured

109 +workspaces.

110

138 -When false, specifying individual workspaces via the `workspace` config, or

139 -all workspaces via the `workspaces` flag, will cause npm to operate only on

140 -the specified workspaces, and not on the root project.

111 +This value is not exported to the environment for child processes.

112

113 <!-- automatically generated, do not edit manually -->

114 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-unpublish.md

+6 -21

@@ -2,15 +2,8 @@

2 title: npm-unpublish

3 section: 1

4 description: Remove a package from the registry

5 -redirect_from:

6 - - /cli/unpublish

7 - - /cli/unpublish.html

8 - - /cli/commands/unpublish

9 - - /cli-commands/unpublish

10 - - /cli-commands/unpublish.html

11 - - /cli-commands/npm-unpublish

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-unpublish.md

8 ---

9

@@ -117,8 +110,8 @@ Valid values for the `workspace` config are either:

110

111 * Workspace names

112 * Path to a workspace directory

120 -* Path to a parent workspace directory (will result in selecting all

121 - workspaces within that folder)

113 +* Path to a parent workspace directory (will result to selecting all of the

114 + nested workspaces)

115

116 When set for the `npm init` command, this may be set to the folder of a

117 workspace which does not yet exist, to create the folder and set it up as a

@@ -131,20 +124,12 @@ This value is not exported to the environment for child processes.

124

125 #### `workspaces`

126

134 -* Default: null

135 -* Type: null or Boolean

127 +* Default: false

128 +* Type: Boolean

129

137 -Set to true to run the command in the context of **all** configured

130 +Enable running a command in the context of **all** the configured

131 workspaces.

132

140 -Explicitly setting this to false will cause commands like `install` to

141 -ignore workspaces altogether. When not set explicitly:

142 -

143 -- Commands that operate on the `node_modules` tree (install, update, etc.)

144 -will link workspaces into the `node_modules` folder. - Commands that do

145 -other things (test, exec, publish, etc.) will operate on the root project,

146 -_unless_ one or more workspaces are specified in the `workspace` config.

147 -

133 This value is not exported to the environment for child processes.

134

135 <!-- automatically generated, do not edit manually -->

content/cli/v7/commands/npm-unstar.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-unstar

3 section: 1

4 description: Remove an item from your favorite packages

5 -redirect_from:

6 - - /cli/unstar

7 - - /cli/unstar.html

8 - - /cli/commands/unstar

9 - - /cli-commands/unstar

10 - - /cli-commands/unstar.html

11 - - /cli-commands/npm-unstar

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-unstar.md

8 ---

9

content/cli/v7/commands/npm-update.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-update

3 section: 1

4 description: Update packages

5 -redirect_from:

6 - - /cli/update

7 - - /cli/update.html

8 - - /cli/commands/update

9 - - /cli-commands/update

10 - - /cli-commands/update.html

11 - - /cli-commands/npm-update

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-update.md

8 ---

9

@@ -351,8 +344,8 @@ Valid values for the `workspace` config are either:

344

345 * Workspace names

346 * Path to a workspace directory

354 -* Path to a parent workspace directory (will result in selecting all

355 - workspaces within that folder)

347 +* Path to a parent workspace directory (will result to selecting all of the

348 + nested workspaces)

349

350 When set for the `npm init` command, this may be set to the folder of a

351 workspace which does not yet exist, to create the folder and set it up as a

@@ -365,35 +358,13 @@ This value is not exported to the environment for child processes.

358

359 #### `workspaces`

360

368 -* Default: null

369 -* Type: null or Boolean

370 -

371 -Set to true to run the command in the context of **all** configured

372 -workspaces.

373 -

374 -Explicitly setting this to false will cause commands like `install` to

375 -ignore workspaces altogether. When not set explicitly:

376 -

377 -- Commands that operate on the `node_modules` tree (install, update, etc.)

378 -will link workspaces into the `node_modules` folder. - Commands that do

379 -other things (test, exec, publish, etc.) will operate on the root project,

380 -_unless_ one or more workspaces are specified in the `workspace` config.

381 -

382 -This value is not exported to the environment for child processes.

383 -

384 -<!-- automatically generated, do not edit manually -->

385 -<!-- see lib/utils/config/definitions.js -->

386 -

387 -#### `include-workspace-root`

388 -

361 * Default: false

362 * Type: Boolean

363

392 -Include the workspace root when workspaces are enabled for a command.

364 +Enable running a command in the context of **all** the configured

365 +workspaces.

366

394 -When false, specifying individual workspaces via the `workspace` config, or

395 -all workspaces via the `workspaces` flag, will cause npm to operate only on

396 -the specified workspaces, and not on the root project.

367 +This value is not exported to the environment for child processes.

368

369 <!-- automatically generated, do not edit manually -->

370 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-version.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-version

3 section: 1

4 description: Bump a package version

5 -redirect_from:

6 - - /cli/version

7 - - /cli/version.html

8 - - /cli/commands/version

9 - - /cli-commands/version

10 - - /cli-commands/version.html

11 - - /cli-commands/npm-version

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-version.md

8 ---

9

@@ -113,8 +106,8 @@ Valid values for the `workspace` config are either:

106

107 * Workspace names

108 * Path to a workspace directory

116 -* Path to a parent workspace directory (will result in selecting all

117 - workspaces within that folder)

109 +* Path to a parent workspace directory (will result to selecting all of the

110 + nested workspaces)

111

112 When set for the `npm init` command, this may be set to the folder of a

113 workspace which does not yet exist, to create the folder and set it up as a

@@ -127,35 +120,13 @@ This value is not exported to the environment for child processes.

120

121 #### `workspaces`

122

130 -* Default: null

131 -* Type: null or Boolean

132 -

133 -Set to true to run the command in the context of **all** configured

134 -workspaces.

135 -

136 -Explicitly setting this to false will cause commands like `install` to

137 -ignore workspaces altogether. When not set explicitly:

138 -

139 -- Commands that operate on the `node_modules` tree (install, update, etc.)

140 -will link workspaces into the `node_modules` folder. - Commands that do

141 -other things (test, exec, publish, etc.) will operate on the root project,

142 -_unless_ one or more workspaces are specified in the `workspace` config.

143 -

144 -This value is not exported to the environment for child processes.

145 -

146 -<!-- automatically generated, do not edit manually -->

147 -<!-- see lib/utils/config/definitions.js -->

148 -

149 -#### `include-workspace-root`

150 -

123 * Default: false

124 * Type: Boolean

125

154 -Include the workspace root when workspaces are enabled for a command.

126 +Enable running a command in the context of **all** the configured

127 +workspaces.

128

156 -When false, specifying individual workspaces via the `workspace` config, or

157 -all workspaces via the `workspaces` flag, will cause npm to operate only on

158 -the specified workspaces, and not on the root project.

129 +This value is not exported to the environment for child processes.

130

131 <!-- automatically generated, do not edit manually -->

132 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-view.md

+6 -35

@@ -2,15 +2,8 @@

2 title: npm-view

3 section: 1

4 description: View registry info

5 -redirect_from:

6 - - /cli/view

7 - - /cli/view.html

8 - - /cli/commands/view

9 - - /cli-commands/view

10 - - /cli-commands/view.html

11 - - /cli-commands/npm-view

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-view.md

8 ---

9

@@ -137,8 +130,8 @@ Valid values for the `workspace` config are either:

130

131 * Workspace names

132 * Path to a workspace directory

140 -* Path to a parent workspace directory (will result in selecting all

141 - workspaces within that folder)

133 +* Path to a parent workspace directory (will result to selecting all of the

134 + nested workspaces)

135

136 When set for the `npm init` command, this may be set to the folder of a

137 workspace which does not yet exist, to create the folder and set it up as a

@@ -151,35 +144,13 @@ This value is not exported to the environment for child processes.

144

145 #### `workspaces`

146

154 -* Default: null

155 -* Type: null or Boolean

156 -

157 -Set to true to run the command in the context of **all** configured

158 -workspaces.

159 -

160 -Explicitly setting this to false will cause commands like `install` to

161 -ignore workspaces altogether. When not set explicitly:

162 -

163 -- Commands that operate on the `node_modules` tree (install, update, etc.)

164 -will link workspaces into the `node_modules` folder. - Commands that do

165 -other things (test, exec, publish, etc.) will operate on the root project,

166 -_unless_ one or more workspaces are specified in the `workspace` config.

167 -

168 -This value is not exported to the environment for child processes.

169 -

170 -<!-- automatically generated, do not edit manually -->

171 -<!-- see lib/utils/config/definitions.js -->

172 -

173 -#### `include-workspace-root`

174 -

147 * Default: false

148 * Type: Boolean

149

178 -Include the workspace root when workspaces are enabled for a command.

150 +Enable running a command in the context of **all** the configured

151 +workspaces.

152

180 -When false, specifying individual workspaces via the `workspace` config, or

181 -all workspaces via the `workspaces` flag, will cause npm to operate only on

182 -the specified workspaces, and not on the root project.

153 +This value is not exported to the environment for child processes.

154

155 <!-- automatically generated, do not edit manually -->

156 <!-- see lib/utils/config/definitions.js -->

content/cli/v7/commands/npm-whoami.md

+1 -8

@@ -2,15 +2,8 @@

2 title: npm-whoami

3 section: 1

4 description: Display npm username

5 -redirect_from:

6 - - /cli/whoami

7 - - /cli/whoami.html

8 - - /cli/commands/whoami

9 - - /cli-commands/whoami

10 - - /cli-commands/whoami.html

11 - - /cli-commands/npm-whoami

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm-whoami.md

8 ---

9

content/cli/v7/commands/npm.md

+1 -7

@@ -2,14 +2,8 @@

2 title: npm

3 section: 1

4 description: javascript package manager

5 -redirect_from:

6 - - /cli/npm

7 - - /cli/npm.html

8 - - /cli/commands/npm

9 - - /cli-commands/npm

10 - - /cli-commands/npm.html

5 github_repo: npm/cli

12 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npm.md

8 ---

9

content/cli/v7/commands/npx.md

+1 -1

@@ -3,7 +3,7 @@ title: npx

3 section: 1

4 description: Run a command from a local or remote npm package

5 github_repo: npm/cli

6 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/commands/npx.md

8 ---

9

content/cli/v7/configuring-npm/folders.md

+1 -6

@@ -2,13 +2,8 @@

2 title: folders

3 section: 5

4 description: Folder Structures Used by npm

5 -redirect_from:

6 - - /configuring-npm/folders

7 - - /configuring-npm/folders.html

8 - - /files/folders

9 - - /files/folders.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/folders.md

8 ---

9

content/cli/v7/configuring-npm/index.mdx

+1 -6

@@ -1,11 +1,6 @@

1 ---

2 -redirect_from:

3 - - configuring-npm

4 - - /cli/configuring-npm

5 - - /cli-documentation/configuring-npm

6 - - /cli-documentation/files

2 github_repo: npm/cli

8 -github_branch: latest

3 +github_branch: v7

4 github_path: docs/content/configuring-npm/index.mdx

5 title: Configuring npm

6 ---

content/cli/v7/configuring-npm/install.md

+1 -4

@@ -2,11 +2,8 @@

2 title: install

3 section: 5

4 description: Download and install node and npm

5 -redirect_from:

6 - - /configuring-npm/install

7 - - /configuring-npm/install.html

5 github_repo: npm/cli

9 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/install.md

8 ---

9

content/cli/v7/configuring-npm/npm-shrinkwrap-json.md

+1 -4

@@ -2,11 +2,8 @@

2 title: npm-shrinkwrap.json

3 section: 5

4 description: A publishable lockfile

5 -redirect_from:

6 - - /configuring-npm/npm-shrinkwrap-json

7 - - /configuring-npm/npm-shrinkwrap-json.html

5 github_repo: npm/cli

9 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/npm-shrinkwrap-json.md

8 ---

9

content/cli/v7/configuring-npm/npmrc.md

+1 -7

@@ -2,14 +2,8 @@

2 title: npmrc

3 section: 5

4 description: The npm config files

5 -redirect_from:

6 - - /configuring-npm/npmrc

7 - - /configuring-npm/npmrc.html

8 - - /cli-documentation/files/npmrc

9 - - /files/npmrc

10 - - /files/npmrc.html

5 github_repo: npm/cli

12 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/npmrc.md

8 ---

9

content/cli/v7/configuring-npm/package-json.md

+1 -8

@@ -2,15 +2,8 @@

2 title: package.json

3 section: 5

4 description: Specifics of npm's package.json handling

5 -redirect_from:

6 - - /configuring-npm/package-json

7 - - /configuring-npm/package-json.html

8 - - /configuring-npm/package.json

9 - - /creating-a-packge-json-file

10 - - /files/package.json

11 - - /files/package.json.html

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/package-json.md

8 ---

9

content/cli/v7/configuring-npm/package-lock-json.md

+1 -6

@@ -2,13 +2,8 @@

2 title: package-lock.json

3 section: 5

4 description: A manifestation of the manifest

5 -redirect_from:

6 - - /configuring-npm/package-lock-json

7 - - /configuring-npm/package-lock-json.html

8 - - /files/package-lock.json

9 - - /files/package-lock.json.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/configuring-npm/package-lock-json.md

8 ---

9

content/cli/v7/index.mdx

+1 -4

@@ -1,9 +1,6 @@

1 ---

2 -redirect_from:

3 - - /cli

4 - - /cli-documentation

2 github_repo: npm/cli

6 -github_branch: latest

3 +github_branch: v7

4 github_path: docs/content/index.mdx

5 title: CLI documentation

6 ---

content/cli/v7/using-npm/config.md

+6 -58

@@ -2,13 +2,8 @@

2 title: config

3 section: 7

4 description: More than you probably want to know about npm configuration

5 -redirect_from:

6 - - /using-npm/config

7 - - /using-npm/config.html

8 - - /misc/config

9 - - /misc/config.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/config.md

8 ---

9

@@ -814,20 +809,6 @@ This is experimental, and not implemented by the npm public registry.

809 <!-- automatically generated, do not edit manually -->

810 <!-- see lib/utils/config/definitions.js -->

811

817 -#### `include-workspace-root`

818 -

819 -* Default: false

820 -* Type: Boolean

821 -

822 -Include the workspace root when workspaces are enabled for a command.

823 -

824 -When false, specifying individual workspaces via the `workspace` config, or

825 -all workspaces via the `workspaces` flag, will cause npm to operate only on

826 -the specified workspaces, and not on the root project.

827 -

828 -<!-- automatically generated, do not edit manually -->

829 -<!-- see lib/utils/config/definitions.js -->

830 -

812 #### `init-author-email`

813

814 * Default: ""

@@ -991,31 +972,6 @@ When passed to `npm config` this refers to which config file to use.

972 <!-- automatically generated, do not edit manually -->

973 <!-- see lib/utils/config/definitions.js -->

974

994 -#### `lockfile-version`

995 -

996 -* Default: Version 2 if no lockfile or current lockfile version less than or

997 - equal to 2, otherwise maintain current lockfile version

998 -* Type: null, 1, 2, 3, "1", "2", or "3"

999 -

1000 -Set the lockfile format version to be used in package-lock.json and

1001 -npm-shrinkwrap-json files. Possible options are:

1002 -

1003 -1: The lockfile version used by npm versions 5 and 6. Lacks some data that

1004 -is used during the install, resulting in slower and possibly less

1005 -deterministic installs. Prevents lockfile churn when interoperating with

1006 -older npm versions.

1007 -

1008 -2: The default lockfile version used by npm version 7. Includes both the

1009 -version 1 lockfile data and version 3 lockfile data, for maximum determinism

1010 -and interoperability, at the expense of more bytes on disk.

1011 -

1012 -3: Only the new lockfile information introduced in npm version 7. Smaller on

1013 -disk than lockfile version 2, but not interoperable with older npm versions.

1014 -Ideal if all users are on npm version 7 and higher.

1015 -

1016 -<!-- automatically generated, do not edit manually -->

1017 -<!-- see lib/utils/config/definitions.js -->

1018 -

975 #### `loglevel`

976

977 * Default: "notice"

@@ -1791,8 +1747,8 @@ Valid values for the `workspace` config are either:

1747

1748 * Workspace names

1749 * Path to a workspace directory

1794 -* Path to a parent workspace directory (will result in selecting all

1795 - workspaces within that folder)

1750 +* Path to a parent workspace directory (will result to selecting all of the

1751 + nested workspaces)

1752

1753 When set for the `npm init` command, this may be set to the folder of a

1754 workspace which does not yet exist, to create the folder and set it up as a

@@ -1805,20 +1761,12 @@ This value is not exported to the environment for child processes.

1761

1762 #### `workspaces`

1763

1808 -* Default: null

1809 -* Type: null or Boolean

1764 +* Default: false

1765 +* Type: Boolean

1766

1811 -Set to true to run the command in the context of **all** configured

1767 +Enable running a command in the context of **all** the configured

1768 workspaces.

1769

1814 -Explicitly setting this to false will cause commands like `install` to

1815 -ignore workspaces altogether. When not set explicitly:

1816 -

1817 -- Commands that operate on the `node_modules` tree (install, update, etc.)

1818 -will link workspaces into the `node_modules` folder. - Commands that do

1819 -other things (test, exec, publish, etc.) will operate on the root project,

1820 -_unless_ one or more workspaces are specified in the `workspace` config.

1821 -

1770 This value is not exported to the environment for child processes.

1771

1772 <!-- automatically generated, do not edit manually -->

content/cli/v7/using-npm/developers.md

+1 -6

@@ -2,13 +2,8 @@

2 title: developers

3 section: 7

4 description: Developer Guide

5 -redirect_from:

6 - - /using-npm/developers

7 - - /using-npm/developers.html

8 - - /misc/developers

9 - - /misc/developers.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/developers.md

8 ---

9

content/cli/v7/using-npm/index.mdx

+1 -7

@@ -1,12 +1,6 @@

1 ---

2 -redirect_from:

3 - - using-npm

4 - - /cli/using-npm

5 - - cli-documentation/misc

6 - - cli-documentation/using-npm

7 - - /misc/index.html

2 github_repo: npm/cli

9 -github_branch: latest

3 +github_branch: v7

4 github_path: docs/content/using-npm/index.mdx

5 title: Using npm

6 ---

content/cli/v7/using-npm/orgs.md

+1 -6

@@ -2,13 +2,8 @@

2 title: orgs

3 section: 7

4 description: Working with Teams & Orgs

5 -redirect_from:

6 - - /using-npm/orgs

7 - - /using-npm/orgs.html

8 - - /misc/orgs

9 - - /misc/orgs.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/orgs.md

8 ---

9

content/cli/v7/using-npm/registry.md

+1 -6

@@ -2,13 +2,8 @@

2 title: registry

3 section: 7

4 description: The JavaScript Package Registry

5 -redirect_from:

6 - - /using-npm/registry

7 - - /using-npm/registry.html

8 - - /misc/registry

9 - - /misc/registry.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/registry.md

8 ---

9

content/cli/v7/using-npm/removal.md

+1 -8

@@ -2,15 +2,8 @@

2 title: removal

3 section: 7

4 description: Cleaning the Slate

5 -redirect_from:

6 - - /using-npm/removal

7 - - /using-npm/removal.html

8 - - /misc/removal

9 - - /misc/removal.html

10 - - /misc/removing-npm

11 - - /misc/removing-npm.html

5 github_repo: npm/cli

13 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/removal.md

8 ---

9

content/cli/v7/using-npm/scope.md

+1 -7

@@ -2,14 +2,8 @@

2 title: scope

3 section: 7

4 description: Scoped packages

5 -redirect_from:

6 - - /using-npm/scope

7 - - /using-npm/scope.html

8 - - /misc/scope

9 - - /misc/scope.html

10 - - /using-npm/npm-scope

5 github_repo: npm/cli

12 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/scope.md

8 ---

9

content/cli/v7/using-npm/scripts.md

+1 -6

@@ -2,13 +2,8 @@

2 title: scripts

3 section: 7

4 description: How npm handles the "scripts" field

5 -redirect_from:

6 - - /using-npm/scripts

7 - - /using-npm/scripts.html

8 - - /misc/scripts

9 - - /misc/scripts.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/scripts.md

8 ---

9

content/cli/v7/using-npm/workspaces.md

+2 -7

@@ -2,13 +2,8 @@

2 title: workspaces

3 section: 7

4 description: Working with workspaces

5 -redirect_from:

6 - - /using-npm/workspaces

7 - - /using-npm/workspaces.html

8 - - /misc/workspaces

9 - - /misc/workspaces.html

5 github_repo: npm/cli

11 -github_branch: latest

6 +github_branch: v7

7 github_path: docs/content/using-npm/workspaces.md

8 ---

9

@@ -117,7 +112,7 @@ respect the provided `workspace` configuration.

112 ### Using workspaces

113

114 Given the [specifities of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace

120 -by its declared `package.json` `name`. Continuing from the example defined

115 +by it's declared `package.json` `name`. Continuing from the example defined

116 above, let's also create a Node.js script that will require the `workspace-a`

117 example module, e.g:

118

content/cli/v8/commands/index.mdx new

+12

@@ -0,0 +1,12 @@

1 +---

2 +redirect_from:

3 + - commands

4 + - /cli/commands

5 + - /cli-documentation/cli

6 + - /cli-documentation/cli-commands

7 +github_repo: npm/cli

8 +github_branch: latest

9 +github_path: docs/content/commands/index.mdx

10 +title: CLI commands

11 +---

12 +<Index depth="1" />

\ No newline at end of file

content/cli/v8/commands/npm-access.md new

+132

@@ -0,0 +1,132 @@

1 +---

2 +title: npm-access

3 +section: 1

4 +description: Set access level on published packages

5 +redirect_from:

6 + - /cli/access

7 + - /cli/access.html

8 + - /cli/commands/access

9 + - /cli-commands/access

10 + - /cli-commands/access.html

11 + - /cli-commands/npm-access

12 + - /cli-documentation/access

13 +github_repo: npm/cli

14 +github_branch: latest

15 +github_path: docs/content/commands/npm-access.md

16 +---

17 +

18 +### Synopsis

19 +

20 +```bash

21 +npm access public [<package>]

22 +npm access restricted [<package>]

23 +

24 +npm access grant <read-only|read-write> <scope:team> [<package>]

25 +npm access revoke <scope:team> [<package>]

26 +

27 +npm access 2fa-required [<package>]

28 +npm access 2fa-not-required [<package>]

29 +

30 +npm access ls-packages [<user>|<scope>|<scope:team>]

31 +npm access ls-collaborators [<package> [<user>]]

32 +npm access edit [<package>]

33 +```

34 +

35 +### Description

36 +

37 +Used to set access controls on private packages.

38 +

39 +For all of the subcommands, `npm access` will perform actions on the packages

40 +in the current working directory if no package name is passed to the

41 +subcommand.

42 +

43 +* public / restricted:

44 + Set a package to be either publicly accessible or restricted.

45 +

46 +* grant / revoke:

47 + Add or remove the ability of users and teams to have read-only or read-write

48 + access to a package.

49 +

50 +* 2fa-required / 2fa-not-required:

51 + Configure whether a package requires that anyone publishing it have two-factor

52 + authentication enabled on their account.

53 +

54 +* ls-packages:

55 + Show all of the packages a user or a team is able to access, along with the

56 + access level, except for read-only public packages (it won't print the whole

57 + registry listing)

58 +

59 +* ls-collaborators:

60 + Show all of the access privileges for a package. Will only show permissions

61 + for packages to which you have at least read access. If `<user>` is passed in,

62 + the list is filtered only to teams _that_ user happens to belong to.

63 +

64 +* edit:

65 + Set the access privileges for a package at once using `$EDITOR`.

66 +

67 +### Details

68 +

69 +`npm access` always operates directly on the current registry, configurable

70 +from the command line using `--registry=<registry url>`.

71 +

72 +Unscoped packages are *always public*.

73 +

74 +Scoped packages *default to restricted*, but you can either publish them as

75 +public using `npm publish --access=public`, or set their access as public using

76 +`npm access public` after the initial publish.

77 +

78 +You must have privileges to set the access of a package:

79 +

80 +* You are an owner of an unscoped or scoped package.

81 +* You are a member of the team that owns a scope.

82 +* You have been given read-write privileges for a package, either as a member

83 + of a team or directly as an owner.

84 +

85 +If you have two-factor authentication enabled then you'll be prompted to

86 +provide an otp token, or may use the `--otp=...` option to specify it on

87 +the command line.

88 +

89 +If your account is not paid, then attempts to publish scoped packages will

90 +fail with an HTTP 402 status code (logically enough), unless you use

91 +`--access=public`.

92 +

93 +Management of teams and team memberships is done with the `npm team` command.

94 +

95 +### Configuration

96 +

97 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

98 +<!-- automatically generated, do not edit manually -->

99 +<!-- see lib/utils/config/definitions.js -->

100 +#### `registry`

101 +

102 +* Default: "https://registry.npmjs.org/"

103 +* Type: URL

104 +

105 +The base URL of the npm registry.

106 +

107 +<!-- automatically generated, do not edit manually -->

108 +<!-- see lib/utils/config/definitions.js -->

109 +

110 +#### `otp`

111 +

112 +* Default: null

113 +* Type: null or String

114 +

115 +This is a one-time password from a two-factor authenticator. It's needed

116 +when publishing or changing package permissions with `npm access`.

117 +

118 +If not set, and a registry response fails with a challenge for a one-time

119 +password, npm will prompt on the command line for one.

120 +

121 +<!-- automatically generated, do not edit manually -->

122 +<!-- see lib/utils/config/definitions.js -->

123 +

124 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

125 +

126 +### See Also

127 +

128 +* [`libnpmaccess`](https://npm.im/libnpmaccess)

129 +* [npm team](/cli/v8/commands/npm-team)

130 +* [npm publish](/cli/v8/commands/npm-publish)

131 +* [npm config](/cli/v8/commands/npm-config)

132 +* [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-adduser.md new

+104

@@ -0,0 +1,104 @@

1 +---

2 +title: npm-adduser

3 +section: 1

4 +description: Add a registry user account

5 +redirect_from:

6 + - /cli/adduser

7 + - /cli/adduser.html

8 + - /cli/commands/adduser

9 + - /cli-commands/adduser

10 + - /cli-commands/adduser.html

11 + - /cli-commands/npm-adduser

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-adduser.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm adduser [--registry=url] [--scope=@orgname] [--auth-type=legacy]

21 +

22 +aliases: login, add-user

23 +```

24 +

25 +Note: This command is unaware of workspaces.

26 +

27 +### Description

28 +

29 +Create or verify a user named `<username>` in the specified registry, and

30 +save the credentials to the `.npmrc` file. If no registry is specified,

31 +the default registry will be used (see [`config`](/cli/v8/using-npm/config)).

32 +

33 +The username, password, and email are read in from prompts.

34 +

35 +To reset your password, go to <https://www.npmjs.com/forgot>

36 +

37 +To change your email address, go to <https://www.npmjs.com/email-edit>

38 +

39 +You may use this command multiple times with the same user account to

40 +authorize on a new machine. When authenticating on a new machine,

41 +the username, password and email address must all match with

42 +your existing record.

43 +

44 +`npm login` is an alias to `adduser` and behaves exactly the same way.

45 +

46 +### Configuration

47 +

48 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

49 +<!-- automatically generated, do not edit manually -->

50 +<!-- see lib/utils/config/definitions.js -->

51 +#### `registry`

52 +

53 +* Default: "https://registry.npmjs.org/"

54 +* Type: URL

55 +

56 +The base URL of the npm registry.

57 +

58 +<!-- automatically generated, do not edit manually -->

59 +<!-- see lib/utils/config/definitions.js -->

60 +

61 +#### `scope`

62 +

63 +* Default: the scope of the current project, if any, or ""

64 +* Type: String

65 +

66 +Associate an operation with a scope for a scoped registry.

67 +

68 +Useful when logging in to or out of a private registry:

69 +

70 +```

71 +# log in, linking the scope to the custom registry

72 +npm login --scope=@mycorp --registry=https://registry.mycorp.com

73 +

74 +# log out, removing the link and the auth token

75 +npm logout --scope=@mycorp

76 +```

77 +

78 +This will cause `@mycorp` to be mapped to the registry for future

79 +installation of packages specified according to the pattern

80 +`@mycorp/package`.

81 +

82 +This will also cause `npm init` to create a scoped package.

83 +

84 +```

85 +# accept all defaults, and create a package named "@foo/whatever",

86 +# instead of just named "whatever"

87 +npm init --scope=@foo --yes

88 +```

89 +

90 +

91 +<!-- automatically generated, do not edit manually -->

92 +<!-- see lib/utils/config/definitions.js -->

93 +

94 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

95 +

96 +### See Also

97 +

98 +* [npm registry](/cli/v8/using-npm/registry)

99 +* [npm config](/cli/v8/commands/npm-config)

100 +* [npmrc](/cli/v8/configuring-npm/npmrc)

101 +* [npm owner](/cli/v8/commands/npm-owner)

102 +* [npm whoami](/cli/v8/commands/npm-whoami)

103 +* [npm token](/cli/v8/commands/npm-token)

104 +* [npm profile](/cli/v8/commands/npm-profile)

content/cli/v8/commands/npm-audit.md new

+378

@@ -0,0 +1,378 @@

1 +---

2 +title: npm-audit

3 +section: 1

4 +description: Run a security audit

5 +redirect_from:

6 + - /cli/audit

7 + - /cli/audit.html

8 + - /cli/commands/audit

9 + - /cli-commands/audit

10 + - /cli-commands/audit.html

11 + - /cli-commands/npm-audit

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-audit.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm audit [--json] [--production] [--audit-level=(low|moderate|high|critical)]

21 +npm audit fix [--force|--package-lock-only|--dry-run|--production|--only=(dev|prod)]

22 +

23 +common options: [--production] [--only=(dev|prod)]

24 +```

25 +

26 +### Description

27 +

28 +The audit command submits a description of the dependencies configured in

29 +your project to your default registry and asks for a report of known

30 +vulnerabilities. If any vulnerabilities are found, then the impact and

31 +appropriate remediation will be calculated. If the `fix` argument is

32 +provided, then remediations will be applied to the package tree.

33 +

34 +The command will exit with a 0 exit code if no vulnerabilities were found.

35 +

36 +Note that some vulnerabilities cannot be fixed automatically and will

37 +require manual intervention or review. Also note that since `npm audit

38 +fix` runs a full-fledged `npm install` under the hood, all configs that

39 +apply to the installer will also apply to `npm install` -- so things like

40 +`npm audit fix --package-lock-only` will work as expected.

41 +

42 +By default, the audit command will exit with a non-zero code if any

43 +vulnerability is found. It may be useful in CI environments to include the

44 +`--audit-level` parameter to specify the minimum vulnerability level that

45 +will cause the command to fail. This option does not filter the report

46 +output, it simply changes the command's failure threshold.

47 +

48 +### Audit Endpoints

49 +

50 +There are two audit endpoints that npm may use to fetch vulnerability

51 +information: the `Bulk Advisory` endpoint and the `Quick Audit` endpoint.

52 +

53 +#### Bulk Advisory Endpoint

54 +

55 +As of version 7, npm uses the much faster `Bulk Advisory` endpoint to

56 +optimize the speed of calculating audit results.

57 +

58 +npm will generate a JSON payload with the name and list of versions of each

59 +package in the tree, and POST it to the default configured registry at

60 +the path `/-/npm/v1/security/advisories/bulk`.

61 +

62 +Any packages in the tree that do not have a `version` field in their

63 +package.json file will be ignored. If any `--omit` options are specified

64 +(either via the `--omit` config, or one of the shorthands such as

65 +`--production`, `--only=dev`, and so on), then packages will be omitted

66 +from the submitted payload as appropriate.

67 +

68 +If the registry responds with an error, or with an invalid response, then

69 +npm will attempt to load advisory data from the `Quick Audit` endpoint.

70 +

71 +The expected result will contain a set of advisory objects for each

72 +dependency that matches the advisory range. Each advisory object contains

73 +a `name`, `url`, `id`, `severity`, `vulnerable_versions`, and `title`.

74 +

75 +npm then uses these advisory objects to calculate vulnerabilities and

76 +meta-vulnerabilities of the dependencies within the tree.

77 +

78 +#### Quick Audit Endpoint

79 +

80 +If the `Bulk Advisory` endpoint returns an error, or invalid data, npm will

81 +attempt to load advisory data from the `Quick Audit` endpoint, which is

82 +considerably slower in most cases.

83 +

84 +The full package tree as found in `package-lock.json` is submitted, along

85 +with the following pieces of additional metadata:

86 +

87 +* `npm_version`

88 +* `node_version`

89 +* `platform`

90 +* `arch`

91 +* `node_env`

92 +

93 +All packages in the tree are submitted to the Quick Audit endpoint.

94 +Omitted dependency types are skipped when generating the report.

95 +

96 +#### Scrubbing

97 +

98 +Out of an abundance of caution, npm versions 5 and 6 would "scrub" any

99 +packages from the submitted report if their name contained a `/` character,

100 +so as to avoid leaking the names of potentially private packages or git

101 +URLs.

102 +

103 +However, in practice, this resulted in audits often failing to properly

104 +detect meta-vulnerabilities, because the tree would appear to be invalid

105 +due to missing dependencies, and prevented the detection of vulnerabilities

106 +in package trees that used git dependencies or private modules.

107 +

108 +This scrubbing has been removed from npm as of version 7.

109 +

110 +#### Calculating Meta-Vulnerabilities and Remediations

111 +

112 +npm uses the

113 +[`@npmcli/metavuln-calculator`](http://npm.im/@npmcli/metavuln-calculator)

114 +module to turn a set of security advisories into a set of "vulnerability"

115 +objects. A "meta-vulnerability" is a dependency that is vulnerable by

116 +virtue of dependence on vulnerable versions of a vulnerable package.

117 +

118 +For example, if the package `foo` is vulnerable in the range `>=1.0.2

119 +<2.0.0`, and the package `bar` depends on `foo@^1.1.0`, then that version

120 +of `bar` can only be installed by installing a vulnerable version of `foo`.

121 +In this case, `bar` is a "metavulnerability".

122 +

123 +Once metavulnerabilities for a given package are calculated, they are

124 +cached in the `~/.npm` folder and only re-evaluated if the advisory range

125 +changes, or a new version of the package is published (in which case, the

126 +new version is checked for metavulnerable status as well).

127 +

128 +If the chain of metavulnerabilities extends all the way to the root

129 +project, and it cannot be updated without changing its dependency ranges,

130 +then `npm audit fix` will require the `--force` option to apply the

131 +remediation. If remediations do not require changes to the dependency

132 +ranges, then all vulnerable packages will be updated to a version that does

133 +not have an advisory or metavulnerability posted against it.

134 +

135 +### Exit Code

136 +

137 +The `npm audit` command will exit with a 0 exit code if no vulnerabilities

138 +were found. The `npm audit fix` command will exit with 0 exit code if no

139 +vulnerabilities are found _or_ if the remediation is able to successfully

140 +fix all vulnerabilities.

141 +

142 +If vulnerabilities were found the exit code will depend on the

143 +`audit-level` configuration setting.

144 +

145 +### Examples

146 +

147 +Scan your project for vulnerabilities and automatically install any compatible

148 +updates to vulnerable dependencies:

149 +

150 +```bash

151 +$ npm audit fix

152 +```

153 +

154 +Run `audit fix` without modifying `node_modules`, but still updating the

155 +pkglock:

156 +

157 +```bash

158 +$ npm audit fix --package-lock-only

159 +```

160 +

161 +Skip updating `devDependencies`:

162 +

163 +```bash

164 +$ npm audit fix --only=prod

165 +```

166 +

167 +Have `audit fix` install SemVer-major updates to toplevel dependencies, not

168 +just SemVer-compatible ones:

169 +

170 +```bash

171 +$ npm audit fix --force

172 +```

173 +

174 +Do a dry run to get an idea of what `audit fix` will do, and _also_ output

175 +install information in JSON format:

176 +

177 +```bash

178 +$ npm audit fix --dry-run --json

179 +```

180 +

181 +Scan your project for vulnerabilities and just show the details, without

182 +fixing anything:

183 +

184 +```bash

185 +$ npm audit

186 +```

187 +

188 +Get the detailed audit report in JSON format:

189 +

190 +```bash

191 +$ npm audit --json

192 +```

193 +

194 +Fail an audit only if the results include a vulnerability with a level of moderate or higher:

195 +

196 +```bash

197 +$ npm audit --audit-level=moderate

198 +```

199 +

200 +### Configuration

201 +

202 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

203 +<!-- automatically generated, do not edit manually -->

204 +<!-- see lib/utils/config/definitions.js -->

205 +#### `audit-level`

206 +

207 +* Default: null

208 +* Type: null, "info", "low", "moderate", "high", "critical", or "none"

209 +

210 +The minimum level of vulnerability for `npm audit` to exit with a non-zero

211 +exit code.

212 +

213 +<!-- automatically generated, do not edit manually -->

214 +<!-- see lib/utils/config/definitions.js -->

215 +

216 +#### `dry-run`

217 +

218 +* Default: false

219 +* Type: Boolean

220 +

221 +Indicates that you don't want npm to make any changes and that it should

222 +only report what it would have done. This can be passed into any of the

223 +commands that modify your local installation, eg, `install`, `update`,

224 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

225 +

226 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

227 +`owner`, etc.

228 +

229 +<!-- automatically generated, do not edit manually -->

230 +<!-- see lib/utils/config/definitions.js -->

231 +

232 +#### `force`

233 +

234 +* Default: false

235 +* Type: Boolean

236 +

237 +Removes various protections against unfortunate side effects, common

238 +mistakes, unnecessary performance degradation, and malicious input.

239 +

240 +* Allow clobbering non-npm files in global installs.

241 +* Allow the `npm version` command to work on an unclean git repository.

242 +* Allow deleting the cache folder with `npm cache clean`.

243 +* Allow installing packages that have an `engines` declaration requiring a

244 + different version of npm.

245 +* Allow installing packages that have an `engines` declaration requiring a

246 + different version of `node`, even if `--engine-strict` is enabled.

247 +* Allow `npm audit fix` to install modules outside your stated dependency

248 + range (including SemVer-major changes).

249 +* Allow unpublishing all versions of a published package.

250 +* Allow conflicting peerDependencies to be installed in the root project.

251 +* Implicitly set `--yes` during `npm init`.

252 +* Allow clobbering existing values in `npm pkg`

253 +

254 +If you don't have a clear idea of what you want to do, it is strongly

255 +recommended that you do not use this option!

256 +

257 +<!-- automatically generated, do not edit manually -->

258 +<!-- see lib/utils/config/definitions.js -->

259 +

260 +#### `json`

261 +

262 +* Default: false

263 +* Type: Boolean

264 +

265 +Whether or not to output JSON data, rather than the normal output.

266 +

267 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

268 + saving them to your `package.json`.

269 +

270 +Not supported by all npm commands.

271 +

272 +<!-- automatically generated, do not edit manually -->

273 +<!-- see lib/utils/config/definitions.js -->

274 +

275 +#### `package-lock-only`

276 +

277 +* Default: false

278 +* Type: Boolean

279 +

280 +If set to true, the current operation will only use the `package-lock.json`,

281 +ignoring `node_modules`.

282 +

283 +For `update` this means only the `package-lock.json` will be updated,

284 +instead of checking `node_modules` and downloading dependencies.

285 +

286 +For `list` this means the output will be based on the tree described by the

287 +`package-lock.json`, rather than the contents of `node_modules`.

288 +

289 +<!-- automatically generated, do not edit manually -->

290 +<!-- see lib/utils/config/definitions.js -->

291 +

292 +#### `omit`

293 +

294 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

295 + 'production', otherwise empty.

296 +* Type: "dev", "optional", or "peer" (can be set multiple times)

297 +

298 +Dependency types to omit from the installation tree on disk.

299 +

300 +Note that these dependencies _are_ still resolved and added to the

301 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

302 +physically installed on disk.

303 +

304 +If a package type appears in both the `--include` and `--omit` lists, then

305 +it will be included.

306 +

307 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

308 +variable will be set to `'production'` for all lifecycle scripts.

309 +

310 +<!-- automatically generated, do not edit manually -->

311 +<!-- see lib/utils/config/definitions.js -->

312 +

313 +#### `workspace`

314 +

315 +* Default:

316 +* Type: String (can be set multiple times)

317 +

318 +Enable running a command in the context of the configured workspaces of the

319 +current project while filtering by running only the workspaces defined by

320 +this configuration option.

321 +

322 +Valid values for the `workspace` config are either:

323 +

324 +* Workspace names

325 +* Path to a workspace directory

326 +* Path to a parent workspace directory (will result in selecting all

327 + workspaces within that folder)

328 +

329 +When set for the `npm init` command, this may be set to the folder of a

330 +workspace which does not yet exist, to create the folder and set it up as a

331 +brand new workspace within the project.

332 +

333 +This value is not exported to the environment for child processes.

334 +

335 +<!-- automatically generated, do not edit manually -->

336 +<!-- see lib/utils/config/definitions.js -->

337 +

338 +#### `workspaces`

339 +

340 +* Default: null

341 +* Type: null or Boolean

342 +

343 +Set to true to run the command in the context of **all** configured

344 +workspaces.

345 +

346 +Explicitly setting this to false will cause commands like `install` to

347 +ignore workspaces altogether. When not set explicitly:

348 +

349 +- Commands that operate on the `node_modules` tree (install, update, etc.)

350 +will link workspaces into the `node_modules` folder. - Commands that do

351 +other things (test, exec, publish, etc.) will operate on the root project,

352 +_unless_ one or more workspaces are specified in the `workspace` config.

353 +

354 +This value is not exported to the environment for child processes.

355 +

356 +<!-- automatically generated, do not edit manually -->

357 +<!-- see lib/utils/config/definitions.js -->

358 +

359 +#### `include-workspace-root`

360 +

361 +* Default: false

362 +* Type: Boolean

363 +

364 +Include the workspace root when workspaces are enabled for a command.

365 +

366 +When false, specifying individual workspaces via the `workspace` config, or

367 +all workspaces via the `workspaces` flag, will cause npm to operate only on

368 +the specified workspaces, and not on the root project.

369 +

370 +<!-- automatically generated, do not edit manually -->

371 +<!-- see lib/utils/config/definitions.js -->

372 +

373 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

374 +

375 +### See Also

376 +

377 +* [npm install](/cli/v8/commands/npm-install)

378 +* [config](/cli/v8/using-npm/config)

content/cli/v8/commands/npm-bin.md new

+59

@@ -0,0 +1,59 @@

1 +---

2 +title: npm-bin

3 +section: 1

4 +description: Display npm bin folder

5 +redirect_from:

6 + - /cli/bin

7 + - /cli/bin.html

8 + - /cli/commands/bin

9 + - /cli-commands/bin

10 + - /cli-commands/bin.html

11 + - /cli-commands/npm-bin

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-bin.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm bin [-g|--global]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Print the folder where npm will install executables.

28 +

29 +### Configuration

30 +

31 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

32 +<!-- automatically generated, do not edit manually -->

33 +<!-- see lib/utils/config/definitions.js -->

34 +#### `global`

35 +

36 +* Default: false

37 +* Type: Boolean

38 +

39 +Operates in "global" mode, so that packages are installed into the `prefix`

40 +folder instead of the current working directory. See

41 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

42 +

43 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

44 + of the current working directory.

45 +* bin files are linked to `{prefix}/bin`

46 +* man pages are linked to `{prefix}/share/man`

47 +

48 +<!-- automatically generated, do not edit manually -->

49 +<!-- see lib/utils/config/definitions.js -->

50 +

51 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

52 +

53 +### See Also

54 +

55 +* [npm prefix](/cli/v8/commands/npm-prefix)

56 +* [npm root](/cli/v8/commands/npm-root)

57 +* [npm folders](/cli/v8/configuring-npm/folders)

58 +* [npm config](/cli/v8/commands/npm-config)

59 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-bugs.md new

+72

@@ -0,0 +1,72 @@

1 +---

2 +title: npm-bugs

3 +section: 1

4 +description: Report bugs for a package in a web browser

5 +redirect_from:

6 + - /cli/bugs

7 + - /cli/bugs.html

8 + - /cli/commands/bugs

9 + - /cli-commands/bugs

10 + - /cli-commands/bugs.html

11 + - /cli-commands/npm-bugs

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-bugs.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm bugs [<pkgname> [<pkgname> ...]]

21 +

22 +aliases: issues

23 +```

24 +

25 +### Description

26 +

27 +This command tries to guess at the likely location of a package's bug

28 +tracker URL or the `mailto` URL of the support email, and then tries to

29 +open it using the `--browser` config param. If no package name is provided, it

30 +will search for a `package.json` in the current folder and use the `name` property.

31 +

32 +### Configuration

33 +

34 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

35 +<!-- automatically generated, do not edit manually -->

36 +<!-- see lib/utils/config/definitions.js -->

37 +#### `browser`

38 +

39 +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`

40 +* Type: null, Boolean, or String

41 +

42 +The browser that is called by npm commands to open websites.

43 +

44 +Set to `false` to suppress browser behavior and instead print urls to

45 +terminal.

46 +

47 +Set to `true` to use default system URL opener.

48 +

49 +<!-- automatically generated, do not edit manually -->

50 +<!-- see lib/utils/config/definitions.js -->

51 +

52 +#### `registry`

53 +

54 +* Default: "https://registry.npmjs.org/"

55 +* Type: URL

56 +

57 +The base URL of the npm registry.

58 +

59 +<!-- automatically generated, do not edit manually -->

60 +<!-- see lib/utils/config/definitions.js -->

61 +

62 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

63 +

64 +### See Also

65 +

66 +* [npm docs](/cli/v8/commands/npm-docs)

67 +* [npm view](/cli/v8/commands/npm-view)

68 +* [npm publish](/cli/v8/commands/npm-publish)

69 +* [npm registry](/cli/v8/using-npm/registry)

70 +* [npm config](/cli/v8/commands/npm-config)

71 +* [npmrc](/cli/v8/configuring-npm/npmrc)

72 +* [package.json](/cli/v8/configuring-npm/package-json)

content/cli/v8/commands/npm-cache.md new

+115

@@ -0,0 +1,115 @@

1 +---

2 +title: npm-cache

3 +section: 1

4 +description: Manipulates packages cache

5 +redirect_from:

6 + - /cli/cache

7 + - /cli/cache.html

8 + - /cli/commands/cache

9 + - /cli-commands/cache

10 + - /cli-commands/cache.html

11 + - /cli-commands/npm-cache

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-cache.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm cache add <tarball file>...

21 +npm cache add <folder>...

22 +npm cache add <tarball url>...

23 +npm cache add <name>@<version>...

24 +

25 +npm cache clean

26 +aliases: npm cache clear, npm cache rm

27 +

28 +npm cache verify

29 +```

30 +

31 +Note: This command is unaware of workspaces.

32 +

33 +### Description

34 +

35 +Used to add, list, or clean the npm cache folder.

36 +

37 +* add:

38 + Add the specified packages to the local cache. This command is primarily

39 + intended to be used internally by npm, but it can provide a way to

40 + add data to the local installation cache explicitly.

41 +

42 +* clean:

43 + Delete all data out of the cache folder. Note that this is typically

44 + unnecessary, as npm's cache is self-healing and resistant to data

45 + corruption issues.

46 +

47 +* verify:

48 + Verify the contents of the cache folder, garbage collecting any unneeded

49 + data, and verifying the integrity of the cache index and all cached data.

50 +

51 +### Details

52 +

53 +npm stores cache data in an opaque directory within the configured `cache`,

54 +named `_cacache`. This directory is a

55 +[`cacache`](http://npm.im/cacache)-based content-addressable cache that

56 +stores all http request data as well as other package-related data. This

57 +directory is primarily accessed through `pacote`, the library responsible

58 +for all package fetching as of npm@5.

59 +

60 +All data that passes through the cache is fully verified for integrity on

61 +both insertion and extraction. Cache corruption will either trigger an

62 +error, or signal to `pacote` that the data must be refetched, which it will

63 +do automatically. For this reason, it should never be necessary to clear

64 +the cache for any reason other than reclaiming disk space, thus why `clean`

65 +now requires `--force` to run.

66 +

67 +There is currently no method exposed through npm to inspect or directly

68 +manage the contents of this cache. In order to access it, `cacache` must be

69 +used directly.

70 +

71 +npm will not remove data by itself: the cache will grow as new packages are

72 +installed.

73 +

74 +### A note about the cache's design

75 +

76 +The npm cache is strictly a cache: it should not be relied upon as a

77 +persistent and reliable data store for package data. npm makes no guarantee

78 +that a previously-cached piece of data will be available later, and will

79 +automatically delete corrupted contents. The primary guarantee that the

80 +cache makes is that, if it does return data, that data will be exactly the

81 +data that was inserted.

82 +

83 +To run an offline verification of existing cache contents, use `npm cache

84 +verify`.

85 +

86 +### Configuration

87 +

88 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

89 +<!-- automatically generated, do not edit manually -->

90 +<!-- see lib/utils/config/definitions.js -->

91 +#### `cache`

92 +

93 +* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm`

94 +* Type: Path

95 +

96 +The location of npm's cache directory. See [`npm

97 +cache`](/cli/v8/commands/npm-cache)

98 +

99 +<!-- automatically generated, do not edit manually -->

100 +<!-- see lib/utils/config/definitions.js -->

101 +

102 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

103 +

104 +### See Also

105 +

106 +* [npm folders](/cli/v8/configuring-npm/folders)

107 +* [npm config](/cli/v8/commands/npm-config)

108 +* [npmrc](/cli/v8/configuring-npm/npmrc)

109 +* [npm install](/cli/v8/commands/npm-install)

110 +* [npm publish](/cli/v8/commands/npm-publish)

111 +* [npm pack](/cli/v8/commands/npm-pack)

112 +* https://npm.im/cacache

113 +* https://npm.im/pacote

114 +* https://npm.im/@npmcli/arborist

115 +* https://npm.im/make-fetch-happen

content/cli/v8/commands/npm-ci.md new

+127

@@ -0,0 +1,127 @@

1 +---

2 +title: npm-ci

3 +section: 1

4 +description: Install a project with a clean slate

5 +redirect_from:

6 + - /cli/ci

7 + - /cli/ci.html

8 + - /cli/commands/ci

9 + - /cli-commands/ci

10 + - /cli-commands/ci.html

11 + - /cli-commands/npm-ci

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-ci.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm ci

21 +```

22 +

23 +### Description

24 +

25 +This command is similar to [`npm install`](/cli/v8/commands/npm-install), except

26 +it's meant to be used in automated environments such as test platforms,

27 +continuous integration, and deployment -- or any situation where you want

28 +to make sure you're doing a clean install of your dependencies.

29 +

30 +`npm ci` will be significantly faster when:

31 +

32 +- There is a `package-lock.json` or `npm-shrinkwrap.json` file.

33 +- The `node_modules` folder is missing or empty.

34 +

35 +In short, the main differences between using `npm install` and `npm ci` are:

36 +

37 +* The project **must** have an existing `package-lock.json` or

38 + `npm-shrinkwrap.json`.

39 +* If dependencies in the package lock do not match those in `package.json`,

40 + `npm ci` will exit with an error, instead of updating the package lock.

41 +* `npm ci` can only install entire projects at a time: individual

42 + dependencies cannot be added with this command.

43 +* If a `node_modules` is already present, it will be automatically removed

44 + before `npm ci` begins its install.

45 +* It will never write to `package.json` or any of the package-locks:

46 + installs are essentially frozen.

47 +

48 +### Example

49 +

50 +Make sure you have a package-lock and an up-to-date install:

51 +

52 +```bash

53 +$ cd ./my/npm/project

54 +$ npm install

55 +added 154 packages in 10s

56 +$ ls | grep package-lock

57 +```

58 +

59 +Run `npm ci` in that project

60 +

61 +```bash

62 +$ npm ci

63 +added 154 packages in 5s

64 +```

65 +

66 +Configure Travis to build using `npm ci` instead of `npm install`:

67 +

68 +```bash

69 +# .travis.yml

70 +install:

71 +- npm ci

72 +# keep the npm cache around to speed up installs

73 +cache:

74 + directories:

75 + - "$HOME/.npm"

76 +```

77 +

78 +### Configuration

79 +

80 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

81 +<!-- automatically generated, do not edit manually -->

82 +<!-- see lib/utils/config/definitions.js -->

83 +#### `audit`

84 +

85 +* Default: true

86 +* Type: Boolean

87 +

88 +When "true" submit audit reports alongside the current npm command to the

89 +default registry and all registries configured for scopes. See the

90 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

91 +submitted.

92 +

93 +<!-- automatically generated, do not edit manually -->

94 +<!-- see lib/utils/config/definitions.js -->

95 +

96 +#### `ignore-scripts`

97 +

98 +* Default: false

99 +* Type: Boolean

100 +

101 +If true, npm does not run scripts specified in package.json files.

102 +

103 +Note that commands explicitly intended to run a particular script, such as

104 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

105 +will still run their intended script if `ignore-scripts` is set, but they

106 +will *not* run any pre- or post-scripts.

107 +

108 +<!-- automatically generated, do not edit manually -->

109 +<!-- see lib/utils/config/definitions.js -->

110 +

111 +#### `script-shell`

112 +

113 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

114 +* Type: null or String

115 +

116 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

117 +init <pkg>` commands.

118 +

119 +<!-- automatically generated, do not edit manually -->

120 +<!-- see lib/utils/config/definitions.js -->

121 +

122 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

123 +

124 +### See Also

125 +

126 +* [npm install](/cli/v8/commands/npm-install)

127 +* [package-lock.json](/cli/v8/configuring-npm/package-lock-json)

content/cli/v8/commands/npm-completion.md new

+51

@@ -0,0 +1,51 @@

1 +---

2 +title: npm-completion

3 +section: 1

4 +description: Tab Completion for npm

5 +redirect_from:

6 + - /cli/completion

7 + - /cli/completion.html

8 + - /cli/commands/completion

9 + - /cli-commands/completion

10 + - /cli-commands/completion.html

11 + - /cli-commands/npm-completion

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-completion.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +source <(npm completion)

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Enables tab-completion in all npm commands.

28 +

29 +The synopsis above

30 +loads the completions into your current shell. Adding it to

31 +your ~/.bashrc or ~/.zshrc will make the completions available

32 +everywhere:

33 +

34 +```bash

35 +npm completion >> ~/.bashrc

36 +npm completion >> ~/.zshrc

37 +```

38 +

39 +You may of course also pipe the output of `npm completion` to a file

40 +such as `/usr/local/etc/bash_completion.d/npm` or

41 +`/etc/bash_completion.d/npm` if you have a system that will read

42 +that file for you.

43 +

44 +When `COMP_CWORD`, `COMP_LINE`, and `COMP_POINT` are defined in the

45 +environment, `npm completion` acts in "plumbing mode", and outputs

46 +completions based on the arguments.

47 +

48 +### See Also

49 +

50 +* [npm developers](/cli/v8/using-npm/developers)

51 +* [npm](/cli/v8/commands/npm)

content/cli/v8/commands/npm-config.md new

+183

@@ -0,0 +1,183 @@

1 +---

2 +title: npm-config

3 +section: 1

4 +description: Manage the npm configuration files

5 +redirect_from:

6 + - /cli/config

7 + - /cli/config.html

8 + - /cli/commands/config

9 + - /cli-commands/config

10 + - /cli-commands/config.html

11 + - /cli-commands/npm-config

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-config.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm config set <key>=<value> [<key>=<value> ...]

21 +npm config get [<key> [<key> ...]]

22 +npm config delete <key> [<key> ...]

23 +npm config list [--json]

24 +npm config edit

25 +npm set <key>=<value> [<key>=<value> ...]

26 +npm get [<key> [<key> ...]]

27 +

28 +alias: c

29 +```

30 +

31 +Note: This command is unaware of workspaces.

32 +

33 +### Description

34 +

35 +npm gets its config settings from the command line, environment

36 +variables, `npmrc` files, and in some cases, the `package.json` file.

37 +

38 +See [npmrc](/cli/v8/configuring-npm/npmrc) for more information about the npmrc

39 +files.

40 +

41 +See [config(7)](/cli/v8/using-npm/config) for a more thorough explanation of the

42 +mechanisms involved, and a full list of config options available.

43 +

44 +The `npm config` command can be used to update and edit the contents

45 +of the user and global npmrc files.

46 +

47 +### Sub-commands

48 +

49 +Config supports the following sub-commands:

50 +

51 +#### set

52 +

53 +```bash

54 +npm config set key=value [key=value...]

55 +npm set key=value [key=value...]

56 +```

57 +

58 +Sets each of the config keys to the value provided.

59 +

60 +If value is omitted, then it sets it to an empty string.

61 +

62 +Note: for backwards compatibility, `npm config set key value` is supported

63 +as an alias for `npm config set key=value`.

64 +

65 +#### get

66 +

67 +```bash

68 +npm config get [key ...]

69 +npm get [key ...]

70 +```

71 +

72 +Echo the config value(s) to stdout.

73 +

74 +If multiple keys are provided, then the values will be prefixed with the

75 +key names.

76 +

77 +If no keys are provided, then this command behaves the same as `npm config

78 +list`.

79 +

80 +#### list

81 +

82 +```bash

83 +npm config list

84 +```

85 +

86 +Show all the config settings. Use `-l` to also show defaults. Use `--json`

87 +to show the settings in json format.

88 +

89 +#### delete

90 +

91 +```bash

92 +npm config delete key [key ...]

93 +```

94 +

95 +Deletes the specified keys from all configuration files.

96 +

97 +#### edit

98 +

99 +```bash

100 +npm config edit

101 +```

102 +

103 +Opens the config file in an editor. Use the `--global` flag to edit the

104 +global config.

105 +

106 +### Configuration

107 +

108 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

109 +<!-- automatically generated, do not edit manually -->

110 +<!-- see lib/utils/config/definitions.js -->

111 +#### `json`

112 +

113 +* Default: false

114 +* Type: Boolean

115 +

116 +Whether or not to output JSON data, rather than the normal output.

117 +

118 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

119 + saving them to your `package.json`.

120 +

121 +Not supported by all npm commands.

122 +

123 +<!-- automatically generated, do not edit manually -->

124 +<!-- see lib/utils/config/definitions.js -->

125 +

126 +#### `global`

127 +

128 +* Default: false

129 +* Type: Boolean

130 +

131 +Operates in "global" mode, so that packages are installed into the `prefix`

132 +folder instead of the current working directory. See

133 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

134 +

135 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

136 + of the current working directory.

137 +* bin files are linked to `{prefix}/bin`

138 +* man pages are linked to `{prefix}/share/man`

139 +

140 +<!-- automatically generated, do not edit manually -->

141 +<!-- see lib/utils/config/definitions.js -->

142 +

143 +#### `editor`

144 +

145 +* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on

146 + Windows, or 'vim' on Unix systems

147 +* Type: String

148 +

149 +The command to run for `npm edit` and `npm config edit`.

150 +

151 +<!-- automatically generated, do not edit manually -->

152 +<!-- see lib/utils/config/definitions.js -->

153 +

154 +#### `location`

155 +

156 +* Default: "user" unless `--global` is passed, which will also set this value

157 + to "global"

158 +* Type: "global", "user", or "project"

159 +

160 +When passed to `npm config` this refers to which config file to use.

161 +

162 +<!-- automatically generated, do not edit manually -->

163 +<!-- see lib/utils/config/definitions.js -->

164 +

165 +#### `long`

166 +

167 +* Default: false

168 +* Type: Boolean

169 +

170 +Show extended information in `ls`, `search`, and `help-search`.

171 +

172 +<!-- automatically generated, do not edit manually -->

173 +<!-- see lib/utils/config/definitions.js -->

174 +

175 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

176 +

177 +### See Also

178 +

179 +* [npm folders](/cli/v8/configuring-npm/folders)

180 +* [npm config](/cli/v8/commands/npm-config)

181 +* [package.json](/cli/v8/configuring-npm/package-json)

182 +* [npmrc](/cli/v8/configuring-npm/npmrc)

183 +* [npm](/cli/v8/commands/npm)

content/cli/v8/commands/npm-dedupe.md new

+314

@@ -0,0 +1,314 @@

1 +---

2 +title: npm-dedupe

3 +section: 1

4 +description: Reduce duplication in the package tree

5 +redirect_from:

6 + - /cli/dedupe

7 + - /cli/dedupe.html

8 + - /cli/commands/dedupe

9 + - /cli-commands/dedupe

10 + - /cli-commands/dedupe.html

11 + - /cli-commands/npm-dedupe

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-dedupe.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm dedupe

21 +npm ddp

22 +

23 +aliases: ddp

24 +```

25 +

26 +### Description

27 +

28 +Searches the local package tree and attempts to simplify the overall

29 +structure by moving dependencies further up the tree, where they can

30 +be more effectively shared by multiple dependent packages.

31 +

32 +For example, consider this dependency graph:

33 +

34 +```

35 +a

36 ++-- b <-- depends on c@1.0.x

37 +| `-- c@1.0.3

38 +`-- d <-- depends on c@~1.0.9

39 + `-- c@1.0.10

40 +```

41 +

42 +In this case, `npm dedupe` will transform the tree to:

43 +

44 +```bash

45 +a

46 ++-- b

47 ++-- d

48 +`-- c@1.0.10

49 +```

50 +

51 +Because of the hierarchical nature of node's module lookup, b and d

52 +will both get their dependency met by the single c package at the root

53 +level of the tree.

54 +

55 +In some cases, you may have a dependency graph like this:

56 +

57 +```

58 +a

59 ++-- b <-- depends on c@1.0.x

60 ++-- c@1.0.3

61 +`-- d <-- depends on c@1.x

62 + `-- c@1.9.9

63 +```

64 +

65 +During the installation process, the `c@1.0.3` dependency for `b` was

66 +placed in the root of the tree. Though `d`'s dependency on `c@1.x` could

67 +have been satisfied by `c@1.0.3`, the newer `c@1.9.0` dependency was used,

68 +because npm favors updates by default, even when doing so causes

69 +duplication.

70 +

71 +Running `npm dedupe` will cause npm to note the duplication and

72 +re-evaluate, deleting the nested `c` module, because the one in the root is

73 +sufficient.

74 +

75 +To prefer deduplication over novelty during the installation process, run

76 +`npm install --prefer-dedupe` or `npm config set prefer-dedupe true`.

77 +

78 +Arguments are ignored. Dedupe always acts on the entire tree.

79 +

80 +Note that this operation transforms the dependency tree, but will never

81 +result in new modules being installed.

82 +

83 +Using `npm find-dupes` will run the command in `--dry-run` mode.

84 +

85 +### Configuration

86 +

87 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

88 +<!-- automatically generated, do not edit manually -->

89 +<!-- see lib/utils/config/definitions.js -->

90 +#### `global-style`

91 +

92 +* Default: false

93 +* Type: Boolean

94 +

95 +Causes npm to install the package into your local `node_modules` folder with

96 +the same layout it uses with the global `node_modules` folder. Only your

97 +direct dependencies will show in `node_modules` and everything they depend

98 +on will be flattened in their `node_modules` folders. This obviously will

99 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

100 +will be preferred.

101 +

102 +<!-- automatically generated, do not edit manually -->

103 +<!-- see lib/utils/config/definitions.js -->

104 +

105 +#### `legacy-bundling`

106 +

107 +* Default: false

108 +* Type: Boolean

109 +

110 +Causes npm to install the package such that versions of npm prior to 1.4,

111 +such as the one included with node 0.8, can install the package. This

112 +eliminates all automatic deduping. If used with `global-style` this option

113 +will be preferred.

114 +

115 +<!-- automatically generated, do not edit manually -->

116 +<!-- see lib/utils/config/definitions.js -->

117 +

118 +#### `strict-peer-deps`

119 +

120 +* Default: false

121 +* Type: Boolean

122 +

123 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

124 +conflicting `peerDependencies` will be treated as an install failure, even

125 +if npm could reasonably guess the appropriate resolution based on non-peer

126 +dependency relationships.

127 +

128 +By default, conflicting `peerDependencies` deep in the dependency graph will

129 +be resolved using the nearest non-peer dependency specification, even if

130 +doing so will result in some packages receiving a peer dependency outside

131 +the range set in their package's `peerDependencies` object.

132 +

133 +When such and override is performed, a warning is printed, explaining the

134 +conflict and the packages involved. If `--strict-peer-deps` is set, then

135 +this warning is treated as a failure.

136 +

137 +<!-- automatically generated, do not edit manually -->

138 +<!-- see lib/utils/config/definitions.js -->

139 +

140 +#### `package-lock`

141 +

142 +* Default: true

143 +* Type: Boolean

144 +

145 +If set to false, then ignore `package-lock.json` files when installing. This

146 +will also prevent _writing_ `package-lock.json` if `save` is true.

147 +

148 +When package package-locks are disabled, automatic pruning of extraneous

149 +modules will also be disabled. To remove extraneous modules with

150 +package-locks disabled use `npm prune`.

151 +

152 +<!-- automatically generated, do not edit manually -->

153 +<!-- see lib/utils/config/definitions.js -->

154 +

155 +#### `omit`

156 +

157 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

158 + 'production', otherwise empty.

159 +* Type: "dev", "optional", or "peer" (can be set multiple times)

160 +

161 +Dependency types to omit from the installation tree on disk.

162 +

163 +Note that these dependencies _are_ still resolved and added to the

164 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

165 +physically installed on disk.

166 +

167 +If a package type appears in both the `--include` and `--omit` lists, then

168 +it will be included.

169 +

170 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

171 +variable will be set to `'production'` for all lifecycle scripts.

172 +

173 +<!-- automatically generated, do not edit manually -->

174 +<!-- see lib/utils/config/definitions.js -->

175 +

176 +#### `ignore-scripts`

177 +

178 +* Default: false

179 +* Type: Boolean

180 +

181 +If true, npm does not run scripts specified in package.json files.

182 +

183 +Note that commands explicitly intended to run a particular script, such as

184 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

185 +will still run their intended script if `ignore-scripts` is set, but they

186 +will *not* run any pre- or post-scripts.

187 +

188 +<!-- automatically generated, do not edit manually -->

189 +<!-- see lib/utils/config/definitions.js -->

190 +

191 +#### `audit`

192 +

193 +* Default: true

194 +* Type: Boolean

195 +

196 +When "true" submit audit reports alongside the current npm command to the

197 +default registry and all registries configured for scopes. See the

198 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

199 +submitted.

200 +

201 +<!-- automatically generated, do not edit manually -->

202 +<!-- see lib/utils/config/definitions.js -->

203 +

204 +#### `bin-links`

205 +

206 +* Default: true

207 +* Type: Boolean

208 +

209 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

210 +executables.

211 +

212 +Set to false to have it not do this. This can be used to work around the

213 +fact that some file systems don't support symlinks, even on ostensibly Unix

214 +systems.

215 +

216 +<!-- automatically generated, do not edit manually -->

217 +<!-- see lib/utils/config/definitions.js -->

218 +

219 +#### `fund`

220 +

221 +* Default: true

222 +* Type: Boolean

223 +

224 +When "true" displays the message at the end of each `npm install`

225 +acknowledging the number of dependencies looking for funding. See [`npm

226 +fund`](/cli/v8/commands/npm-fund) for details.

227 +

228 +<!-- automatically generated, do not edit manually -->

229 +<!-- see lib/utils/config/definitions.js -->

230 +

231 +#### `dry-run`

232 +

233 +* Default: false

234 +* Type: Boolean

235 +

236 +Indicates that you don't want npm to make any changes and that it should

237 +only report what it would have done. This can be passed into any of the

238 +commands that modify your local installation, eg, `install`, `update`,

239 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

240 +

241 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

242 +`owner`, etc.

243 +

244 +<!-- automatically generated, do not edit manually -->

245 +<!-- see lib/utils/config/definitions.js -->

246 +

247 +#### `workspace`

248 +

249 +* Default:

250 +* Type: String (can be set multiple times)

251 +

252 +Enable running a command in the context of the configured workspaces of the

253 +current project while filtering by running only the workspaces defined by

254 +this configuration option.

255 +

256 +Valid values for the `workspace` config are either:

257 +

258 +* Workspace names

259 +* Path to a workspace directory

260 +* Path to a parent workspace directory (will result in selecting all

261 + workspaces within that folder)

262 +

263 +When set for the `npm init` command, this may be set to the folder of a

264 +workspace which does not yet exist, to create the folder and set it up as a

265 +brand new workspace within the project.

266 +

267 +This value is not exported to the environment for child processes.

268 +

269 +<!-- automatically generated, do not edit manually -->

270 +<!-- see lib/utils/config/definitions.js -->

271 +

272 +#### `workspaces`

273 +

274 +* Default: null

275 +* Type: null or Boolean

276 +

277 +Set to true to run the command in the context of **all** configured

278 +workspaces.

279 +

280 +Explicitly setting this to false will cause commands like `install` to

281 +ignore workspaces altogether. When not set explicitly:

282 +

283 +- Commands that operate on the `node_modules` tree (install, update, etc.)

284 +will link workspaces into the `node_modules` folder. - Commands that do

285 +other things (test, exec, publish, etc.) will operate on the root project,

286 +_unless_ one or more workspaces are specified in the `workspace` config.

287 +

288 +This value is not exported to the environment for child processes.

289 +

290 +<!-- automatically generated, do not edit manually -->

291 +<!-- see lib/utils/config/definitions.js -->

292 +

293 +#### `include-workspace-root`

294 +

295 +* Default: false

296 +* Type: Boolean

297 +

298 +Include the workspace root when workspaces are enabled for a command.

299 +

300 +When false, specifying individual workspaces via the `workspace` config, or

301 +all workspaces via the `workspaces` flag, will cause npm to operate only on

302 +the specified workspaces, and not on the root project.

303 +

304 +<!-- automatically generated, do not edit manually -->

305 +<!-- see lib/utils/config/definitions.js -->

306 +

307 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

308 +

309 +### See Also

310 +

311 +* [npm find-dupes](/cli/v8/commands/npm-find-dupes)

312 +* [npm ls](/cli/v8/commands/npm-ls)

313 +* [npm update](/cli/v8/commands/npm-update)

314 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/commands/npm-deprecate.md new

+89

@@ -0,0 +1,89 @@

1 +---

2 +title: npm-deprecate

3 +section: 1

4 +description: Deprecate a version of a package

5 +redirect_from:

6 + - /cli/deprecate

7 + - /cli/deprecate.html

8 + - /cli/commands/deprecate

9 + - /cli-commands/deprecate

10 + - /cli-commands/deprecate.html

11 + - /cli-commands/npm-deprecate

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-deprecate.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm deprecate <pkg>[@<version range>] <message>

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +This command will update the npm registry entry for a package, providing a

28 +deprecation warning to all who attempt to install it.

29 +

30 +It works on [version ranges](https://semver.npmjs.com/) as well as specific

31 +versions, so you can do something like this:

32 +

33 +```bash

34 +npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"

35 +```

36 +

37 +SemVer ranges passed to this command are interpreted such that they *do*

38 +include prerelease versions. For example:

39 +

40 +```bash

41 +npm deprecate my-thing@1.x "1.x is no longer supported"

42 +```

43 +

44 +In this case, a version `my-thing@1.0.0-beta.0` will also be deprecated.

45 +

46 +You must be the package owner to deprecate something. See the `owner` and

47 +`adduser` help topics.

48 +

49 +To un-deprecate a package, specify an empty string (`""`) for the `message`

50 +argument. Note that you must use double quotes with no space between them to

51 +format an empty string.

52 +

53 +### Configuration

54 +

55 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

56 +<!-- automatically generated, do not edit manually -->

57 +<!-- see lib/utils/config/definitions.js -->

58 +#### `registry`

59 +

60 +* Default: "https://registry.npmjs.org/"

61 +* Type: URL

62 +

63 +The base URL of the npm registry.

64 +

65 +<!-- automatically generated, do not edit manually -->

66 +<!-- see lib/utils/config/definitions.js -->

67 +

68 +#### `otp`

69 +

70 +* Default: null

71 +* Type: null or String

72 +

73 +This is a one-time password from a two-factor authenticator. It's needed

74 +when publishing or changing package permissions with `npm access`.

75 +

76 +If not set, and a registry response fails with a challenge for a one-time

77 +password, npm will prompt on the command line for one.

78 +

79 +<!-- automatically generated, do not edit manually -->

80 +<!-- see lib/utils/config/definitions.js -->

81 +

82 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

83 +

84 +### See Also

85 +

86 +* [npm publish](/cli/v8/commands/npm-publish)

87 +* [npm registry](/cli/v8/using-npm/registry)

88 +* [npm owner](/cli/v8/commands/npm-owner)

89 +* [npm adduser](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm-diff.md new

+352

@@ -0,0 +1,352 @@

1 +---

2 +title: npm-diff

3 +section: 1

4 +description: The registry diff command

5 +redirect_from:

6 + - /cli/diff

7 + - /cli/diff.html

8 + - /cli/commands/diff

9 + - /cli-commands/diff

10 + - /cli-commands/diff.html

11 + - /cli-commands/npm-diff

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-diff.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm diff [...<paths>]

21 +npm diff --diff=<pkg-name> [...<paths>]

22 +npm diff --diff=<version-a> [--diff=<version-b>] [...<paths>]

23 +npm diff --diff=<spec-a> [--diff=<spec-b>] [...<paths>]

24 +npm diff [--diff-ignore-all-space] [--diff-name-only] [...<paths>]

25 +```

26 +

27 +### Description

28 +

29 +Similar to its `git diff` counterpart, this command will print diff patches

30 +of files for packages published to the npm registry.

31 +

32 +* `npm diff --diff=<spec-a> --diff=<spec-b>`

33 +

34 + Compares two package versions using their registry specifiers, e.g:

35 + `npm diff --diff=pkg@1.0.0 --diff=pkg@^2.0.0`. It's also possible to

36 + compare across forks of any package,

37 + e.g: `npm diff --diff=pkg@1.0.0 --diff=pkg-fork@1.0.0`.

38 +

39 + Any valid spec can be used, so that it's also possible to compare

40 + directories or git repositories,

41 + e.g: `npm diff --diff=pkg@latest --diff=./packages/pkg`

42 +

43 + Here's an example comparing two different versions of a package named

44 + `abbrev` from the registry:

45 +

46 + ```bash

47 + npm diff --diff=abbrev@1.1.0 --diff=abbrev@1.1.1

48 + ```

49 +

50 + On success, output looks like:

51 +

52 + ```bash

53 + diff --git a/package.json b/package.json

54 + index v1.1.0..v1.1.1 100644

55 + --- a/package.json

56 + +++ b/package.json

57 + @@ -1,6 +1,6 @@

58 + {

59 + "name": "abbrev",

60 + - "version": "1.1.0",

61 + + "version": "1.1.1",

62 + "description": "Like ruby's abbrev module, but in js",

63 + "author": "Isaac Z. Schlueter <i@izs.me>",

64 + "main": "abbrev.js",

65 + ```

66 +

67 + Given the flexible nature of npm specs, you can also target local

68 + directories or git repos just like when using `npm install`:

69 +

70 + ```bash

71 + npm diff --diff=https://github.com/npm/libnpmdiff --diff=./local-path

72 + ```

73 +

74 + In the example above we can compare the contents from the package installed

75 + from the git repo at `github.com/npm/libnpmdiff` with the contents of the

76 + `./local-path` that contains a valid package, such as a modified copy of

77 + the original.

78 +

79 +* `npm diff` (in a package directory, no arguments):

80 +

81 + If the package is published to the registry, `npm diff` will fetch the

82 + tarball version tagged as `latest` (this value can be configured using the

83 + `tag` option) and proceed to compare the contents of files present in that

84 + tarball, with the current files in your local file system.

85 +

86 + This workflow provides a handy way for package authors to see what

87 + package-tracked files have been changed in comparison with the latest

88 + published version of that package.

89 +

90 +* `npm diff --diff=<pkg-name>` (in a package directory):

91 +

92 + When using a single package name (with no version or tag specifier) as an

93 + argument, `npm diff` will work in a similar way to

94 + [`npm-outdated`](npm-outdated) and reach for the registry to figure out

95 + what current published version of the package named `<pkg-name>`

96 + will satisfy its dependent declared semver-range. Once that specific

97 + version is known `npm diff` will print diff patches comparing the

98 + current version of `<pkg-name>` found in the local file system with

99 + that specific version returned by the registry.

100 +

101 + Given a package named `abbrev` that is currently installed:

102 +

103 + ```bash

104 + npm diff --diff=abbrev

105 + ```

106 +

107 + That will request from the registry its most up to date version and

108 + will print a diff output comparing the currently installed version to this

109 + newer one if the version numbers are not the same.

110 +

111 +* `npm diff --diff=<spec-a>` (in a package directory):

112 +

113 + Similar to using only a single package name, it's also possible to declare

114 + a full registry specifier version if you wish to compare the local version

115 + of an installed package with the specific version/tag/semver-range provided

116 + in `<spec-a>`.

117 +

118 + An example: assuming `pkg@1.0.0` is installed in the current `node_modules`

119 + folder, running:

120 +

121 + ```bash

122 + npm diff --diff=pkg@2.0.0

123 + ```

124 +

125 + It will effectively be an alias to

126 + `npm diff --diff=pkg@1.0.0 --diff=pkg@2.0.0`.

127 +

128 +* `npm diff --diff=<semver-a> [--diff=<semver-b>]` (in a package directory):

129 +

130 + Using `npm diff` along with semver-valid version numbers is a shorthand

131 + to compare different versions of the current package.

132 +

133 + It needs to be run from a package directory, such that for a package named

134 + `pkg` running `npm diff --diff=1.0.0 --diff=1.0.1` is the same as running

135 + `npm diff --diff=pkg@1.0.0 --diff=pkg@1.0.1`.

136 +

137 + If only a single argument `<version-a>` is provided, then the current local

138 + file system is going to be compared against that version.

139 +

140 + Here's an example comparing two specific versions (published to the

141 + configured registry) of the current project directory:

142 +

143 + ```bash

144 + npm diff --diff=1.0.0 --diff=1.1.0

145 + ```

146 +

147 +Note that tag names are not valid `--diff` argument values, if you wish to

148 +compare to a published tag, you must use the `pkg@tagname` syntax.

149 +

150 +#### Filtering files

151 +

152 +It's possible to also specify positional arguments using file names or globs

153 +pattern matching in order to limit the result of diff patches to only a subset

154 +of files for a given package, e.g:

155 +

156 + ```bash

157 + npm diff --diff=pkg@2 ./lib/ CHANGELOG.md

158 + ```

159 +

160 +In the example above the diff output is only going to print contents of files

161 +located within the folder `./lib/` and changed lines of code within the

162 +`CHANGELOG.md` file.

163 +

164 +### Configuration

165 +

166 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

167 +<!-- automatically generated, do not edit manually -->

168 +<!-- see lib/utils/config/definitions.js -->

169 +#### `diff`

170 +

171 +* Default:

172 +* Type: String (can be set multiple times)

173 +

174 +Define arguments to compare in `npm diff`.

175 +

176 +<!-- automatically generated, do not edit manually -->

177 +<!-- see lib/utils/config/definitions.js -->

178 +

179 +#### `diff-name-only`

180 +

181 +* Default: false

182 +* Type: Boolean

183 +

184 +Prints only filenames when using `npm diff`.

185 +

186 +<!-- automatically generated, do not edit manually -->

187 +<!-- see lib/utils/config/definitions.js -->

188 +

189 +#### `diff-unified`

190 +

191 +* Default: 3

192 +* Type: Number

193 +

194 +The number of lines of context to print in `npm diff`.

195 +

196 +<!-- automatically generated, do not edit manually -->

197 +<!-- see lib/utils/config/definitions.js -->

198 +

199 +#### `diff-ignore-all-space`

200 +

201 +* Default: false

202 +* Type: Boolean

203 +

204 +Ignore whitespace when comparing lines in `npm diff`.

205 +

206 +<!-- automatically generated, do not edit manually -->

207 +<!-- see lib/utils/config/definitions.js -->

208 +

209 +#### `diff-no-prefix`

210 +

211 +* Default: false

212 +* Type: Boolean

213 +

214 +Do not show any source or destination prefix in `npm diff` output.

215 +

216 +Note: this causes `npm diff` to ignore the `--diff-src-prefix` and

217 +`--diff-dst-prefix` configs.

218 +

219 +<!-- automatically generated, do not edit manually -->

220 +<!-- see lib/utils/config/definitions.js -->

221 +

222 +#### `diff-src-prefix`

223 +

224 +* Default: "a/"

225 +* Type: String

226 +

227 +Source prefix to be used in `npm diff` output.

228 +

229 +<!-- automatically generated, do not edit manually -->

230 +<!-- see lib/utils/config/definitions.js -->

231 +

232 +#### `diff-dst-prefix`

233 +

234 +* Default: "b/"

235 +* Type: String

236 +

237 +Destination prefix to be used in `npm diff` output.

238 +

239 +<!-- automatically generated, do not edit manually -->

240 +<!-- see lib/utils/config/definitions.js -->

241 +

242 +#### `diff-text`

243 +

244 +* Default: false

245 +* Type: Boolean

246 +

247 +Treat all files as text in `npm diff`.

248 +

249 +<!-- automatically generated, do not edit manually -->

250 +<!-- see lib/utils/config/definitions.js -->

251 +

252 +#### `global`

253 +

254 +* Default: false

255 +* Type: Boolean

256 +

257 +Operates in "global" mode, so that packages are installed into the `prefix`

258 +folder instead of the current working directory. See

259 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

260 +

261 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

262 + of the current working directory.

263 +* bin files are linked to `{prefix}/bin`

264 +* man pages are linked to `{prefix}/share/man`

265 +

266 +<!-- automatically generated, do not edit manually -->

267 +<!-- see lib/utils/config/definitions.js -->

268 +

269 +#### `tag`

270 +

271 +* Default: "latest"

272 +* Type: String

273 +

274 +If you ask npm to install a package and don't tell it a specific version,

275 +then it will install the specified tag.

276 +

277 +Also the tag that is added to the package@version specified by the `npm tag`

278 +command, if no explicit tag is given.

279 +

280 +When used by the `npm diff` command, this is the tag used to fetch the

281 +tarball that will be compared with the local files by default.

282 +

283 +<!-- automatically generated, do not edit manually -->

284 +<!-- see lib/utils/config/definitions.js -->

285 +

286 +#### `workspace`

287 +

288 +* Default:

289 +* Type: String (can be set multiple times)

290 +

291 +Enable running a command in the context of the configured workspaces of the

292 +current project while filtering by running only the workspaces defined by

293 +this configuration option.

294 +

295 +Valid values for the `workspace` config are either:

296 +

297 +* Workspace names

298 +* Path to a workspace directory

299 +* Path to a parent workspace directory (will result in selecting all

300 + workspaces within that folder)

301 +

302 +When set for the `npm init` command, this may be set to the folder of a

303 +workspace which does not yet exist, to create the folder and set it up as a

304 +brand new workspace within the project.

305 +

306 +This value is not exported to the environment for child processes.

307 +

308 +<!-- automatically generated, do not edit manually -->

309 +<!-- see lib/utils/config/definitions.js -->

310 +

311 +#### `workspaces`

312 +

313 +* Default: null

314 +* Type: null or Boolean

315 +

316 +Set to true to run the command in the context of **all** configured

317 +workspaces.

318 +

319 +Explicitly setting this to false will cause commands like `install` to

320 +ignore workspaces altogether. When not set explicitly:

321 +

322 +- Commands that operate on the `node_modules` tree (install, update, etc.)

323 +will link workspaces into the `node_modules` folder. - Commands that do

324 +other things (test, exec, publish, etc.) will operate on the root project,

325 +_unless_ one or more workspaces are specified in the `workspace` config.

326 +

327 +This value is not exported to the environment for child processes.

328 +

329 +<!-- automatically generated, do not edit manually -->

330 +<!-- see lib/utils/config/definitions.js -->

331 +

332 +#### `include-workspace-root`

333 +

334 +* Default: false

335 +* Type: Boolean

336 +

337 +Include the workspace root when workspaces are enabled for a command.

338 +

339 +When false, specifying individual workspaces via the `workspace` config, or

340 +all workspaces via the `workspaces` flag, will cause npm to operate only on

341 +the specified workspaces, and not on the root project.

342 +

343 +<!-- automatically generated, do not edit manually -->

344 +<!-- see lib/utils/config/definitions.js -->

345 +

346 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

347 +## See Also

348 +

349 +* [npm outdated](/cli/v8/commands/npm-outdated)

350 +* [npm install](/cli/v8/commands/npm-install)

351 +* [npm config](/cli/v8/commands/npm-config)

352 +* [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-dist-tag.md new

+175

@@ -0,0 +1,175 @@

1 +---

2 +title: npm-dist-tag

3 +section: 1

4 +description: Modify package distribution tags

5 +redirect_from:

6 + - /cli/dist-tag

7 + - /cli/dist-tag.html

8 + - /cli/commands/dist-tag

9 + - /cli-commands/dist-tag

10 + - /cli-commands/dist-tag.html

11 + - /cli-commands/npm-dist-tag

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-dist-tag.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm dist-tag add <pkg>@<version> [<tag>]

21 +npm dist-tag rm <pkg> <tag>

22 +npm dist-tag ls [<pkg>]

23 +

24 +aliases: dist-tags

25 +```

26 +

27 +### Description

28 +

29 +Add, remove, and enumerate distribution tags on a package:

30 +

31 +* add: Tags the specified version of the package with the specified tag, or

32 + the `--tag` config if not specified. If you have two-factor

33 + authentication on auth-and-writes then you’ll need to include a one-time

34 + password on the command line with `--otp <one-time password>`, or at the

35 + OTP prompt.

36 +

37 +* rm: Clear a tag that is no longer in use from the package. If you have

38 + two-factor authentication on auth-and-writes then you’ll need to include

39 + a one-time password on the command line with `--otp <one-time password>`,

40 + or at the OTP prompt.

41 +

42 +* ls: Show all of the dist-tags for a package, defaulting to the package in

43 + the current prefix. This is the default action if none is specified.

44 +

45 +A tag can be used when installing packages as a reference to a version instead

46 +of using a specific version number:

47 +

48 +```bash

49 +npm install <name>@<tag>

50 +```

51 +

52 +When installing dependencies, a preferred tagged version may be specified:

53 +

54 +```bash

55 +npm install --tag <tag>

56 +```

57 +

58 +(This also applies to any other commands that resolve and install

59 +dependencies, such as `npm dedupe`, `npm update`, and `npm audit fix`.)

60 +

61 +Publishing a package sets the `latest` tag to the published version unless the

62 +`--tag` option is used. For example, `npm publish --tag=beta`.

63 +

64 +By default, `npm install <pkg>` (without any `@<version>` or `@<tag>`

65 +specifier) installs the `latest` tag.

66 +

67 +### Purpose

68 +

69 +Tags can be used to provide an alias instead of version numbers.

70 +

71 +For example, a project might choose to have multiple streams of development

72 +and use a different tag for each stream, e.g., `stable`, `beta`, `dev`,

73 +`canary`.

74 +

75 +By default, the `latest` tag is used by npm to identify the current version

76 +of a package, and `npm install <pkg>` (without any `@<version>` or `@<tag>`

77 +specifier) installs the `latest` tag. Typically, projects only use the

78 +`latest` tag for stable release versions, and use other tags for unstable

79 +versions such as prereleases.

80 +

81 +The `next` tag is used by some projects to identify the upcoming version.

82 +

83 +Other than `latest`, no tag has any special significance to npm itself.

84 +

85 +### Caveats

86 +

87 +This command used to be known as `npm tag`, which only created new tags,

88 +and so had a different syntax.

89 +

90 +Tags must share a namespace with version numbers, because they are

91 +specified in the same slot: `npm install <pkg>@<version>` vs

92 +`npm install <pkg>@<tag>`.

93 +

94 +Tags that can be interpreted as valid semver ranges will be rejected. For

95 +example, `v1.4` cannot be used as a tag, because it is interpreted by

96 +semver as `>=1.4.0 <1.5.0`. See <https://github.com/npm/npm/issues/6082>.

97 +

98 +The simplest way to avoid semver problems with tags is to use tags that do

99 +not begin with a number or the letter `v`.

100 +

101 +### Configuration

102 +

103 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

104 +<!-- automatically generated, do not edit manually -->

105 +<!-- see lib/utils/config/definitions.js -->

106 +#### `workspace`

107 +

108 +* Default:

109 +* Type: String (can be set multiple times)

110 +

111 +Enable running a command in the context of the configured workspaces of the

112 +current project while filtering by running only the workspaces defined by

113 +this configuration option.

114 +

115 +Valid values for the `workspace` config are either:

116 +

117 +* Workspace names

118 +* Path to a workspace directory

119 +* Path to a parent workspace directory (will result in selecting all

120 + workspaces within that folder)

121 +

122 +When set for the `npm init` command, this may be set to the folder of a

123 +workspace which does not yet exist, to create the folder and set it up as a

124 +brand new workspace within the project.

125 +

126 +This value is not exported to the environment for child processes.

127 +

128 +<!-- automatically generated, do not edit manually -->

129 +<!-- see lib/utils/config/definitions.js -->

130 +

131 +#### `workspaces`

132 +

133 +* Default: null

134 +* Type: null or Boolean

135 +

136 +Set to true to run the command in the context of **all** configured

137 +workspaces.

138 +

139 +Explicitly setting this to false will cause commands like `install` to

140 +ignore workspaces altogether. When not set explicitly:

141 +

142 +- Commands that operate on the `node_modules` tree (install, update, etc.)

143 +will link workspaces into the `node_modules` folder. - Commands that do

144 +other things (test, exec, publish, etc.) will operate on the root project,

145 +_unless_ one or more workspaces are specified in the `workspace` config.

146 +

147 +This value is not exported to the environment for child processes.

148 +

149 +<!-- automatically generated, do not edit manually -->

150 +<!-- see lib/utils/config/definitions.js -->

151 +

152 +#### `include-workspace-root`

153 +

154 +* Default: false

155 +* Type: Boolean

156 +

157 +Include the workspace root when workspaces are enabled for a command.

158 +

159 +When false, specifying individual workspaces via the `workspace` config, or

160 +all workspaces via the `workspaces` flag, will cause npm to operate only on

161 +the specified workspaces, and not on the root project.

162 +

163 +<!-- automatically generated, do not edit manually -->

164 +<!-- see lib/utils/config/definitions.js -->

165 +

166 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

167 +

168 +### See Also

169 +

170 +* [npm publish](/cli/v8/commands/npm-publish)

171 +* [npm install](/cli/v8/commands/npm-install)

172 +* [npm dedupe](/cli/v8/commands/npm-dedupe)

173 +* [npm registry](/cli/v8/using-npm/registry)

174 +* [npm config](/cli/v8/commands/npm-config)

175 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-docs.md new

+132

@@ -0,0 +1,132 @@

1 +---

2 +title: npm-docs

3 +section: 1

4 +description: Open documentation for a package in a web browser

5 +redirect_from:

6 + - /cli/docs

7 + - /cli/docs.html

8 + - /cli/commands/docs

9 + - /cli-commands/docs

10 + - /cli-commands/docs.html

11 + - /cli-commands/npm-docs

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-docs.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm docs [<pkgname> [<pkgname> ...]]

21 +

22 +aliases: home

23 +```

24 +

25 +### Description

26 +

27 +This command tries to guess at the likely location of a package's

28 +documentation URL, and then tries to open it using the `--browser` config

29 +param. You can pass multiple package names at once. If no package name is

30 +provided, it will search for a `package.json` in the current folder and use

31 +the `name` property.

32 +

33 +### Configuration

34 +

35 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

36 +<!-- automatically generated, do not edit manually -->

37 +<!-- see lib/utils/config/definitions.js -->

38 +#### `browser`

39 +

40 +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`

41 +* Type: null, Boolean, or String

42 +

43 +The browser that is called by npm commands to open websites.

44 +

45 +Set to `false` to suppress browser behavior and instead print urls to

46 +terminal.

47 +

48 +Set to `true` to use default system URL opener.

49 +

50 +<!-- automatically generated, do not edit manually -->

51 +<!-- see lib/utils/config/definitions.js -->

52 +

53 +#### `registry`

54 +

55 +* Default: "https://registry.npmjs.org/"

56 +* Type: URL

57 +

58 +The base URL of the npm registry.

59 +

60 +<!-- automatically generated, do not edit manually -->

61 +<!-- see lib/utils/config/definitions.js -->

62 +

63 +#### `workspace`

64 +

65 +* Default:

66 +* Type: String (can be set multiple times)

67 +

68 +Enable running a command in the context of the configured workspaces of the

69 +current project while filtering by running only the workspaces defined by

70 +this configuration option.

71 +

72 +Valid values for the `workspace` config are either:

73 +

74 +* Workspace names

75 +* Path to a workspace directory

76 +* Path to a parent workspace directory (will result in selecting all

77 + workspaces within that folder)

78 +

79 +When set for the `npm init` command, this may be set to the folder of a

80 +workspace which does not yet exist, to create the folder and set it up as a

81 +brand new workspace within the project.

82 +

83 +This value is not exported to the environment for child processes.

84 +

85 +<!-- automatically generated, do not edit manually -->

86 +<!-- see lib/utils/config/definitions.js -->

87 +

88 +#### `workspaces`

89 +

90 +* Default: null

91 +* Type: null or Boolean

92 +

93 +Set to true to run the command in the context of **all** configured

94 +workspaces.

95 +

96 +Explicitly setting this to false will cause commands like `install` to

97 +ignore workspaces altogether. When not set explicitly:

98 +

99 +- Commands that operate on the `node_modules` tree (install, update, etc.)

100 +will link workspaces into the `node_modules` folder. - Commands that do

101 +other things (test, exec, publish, etc.) will operate on the root project,

102 +_unless_ one or more workspaces are specified in the `workspace` config.

103 +

104 +This value is not exported to the environment for child processes.

105 +

106 +<!-- automatically generated, do not edit manually -->

107 +<!-- see lib/utils/config/definitions.js -->

108 +

109 +#### `include-workspace-root`

110 +

111 +* Default: false

112 +* Type: Boolean

113 +

114 +Include the workspace root when workspaces are enabled for a command.

115 +

116 +When false, specifying individual workspaces via the `workspace` config, or

117 +all workspaces via the `workspaces` flag, will cause npm to operate only on

118 +the specified workspaces, and not on the root project.

119 +

120 +<!-- automatically generated, do not edit manually -->

121 +<!-- see lib/utils/config/definitions.js -->

122 +

123 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

124 +

125 +### See Also

126 +

127 +* [npm view](/cli/v8/commands/npm-view)

128 +* [npm publish](/cli/v8/commands/npm-publish)

129 +* [npm registry](/cli/v8/using-npm/registry)

130 +* [npm config](/cli/v8/commands/npm-config)

131 +* [npmrc](/cli/v8/configuring-npm/npmrc)

132 +* [package.json](/cli/v8/configuring-npm/package-json)

content/cli/v8/commands/npm-doctor.md new

+136

@@ -0,0 +1,136 @@

1 +---

2 +title: npm-doctor

3 +section: 1

4 +description: Check your npm environment

5 +redirect_from:

6 + - /cli/doctor

7 + - /cli/doctor.html

8 + - /cli/commands/doctor

9 + - /cli-commands/doctor

10 + - /cli-commands/doctor.html

11 + - /cli-commands/npm-doctor

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-doctor.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm doctor

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +`npm doctor` runs a set of checks to ensure that your npm installation has

28 +what it needs to manage your JavaScript packages. npm is mostly a

29 +standalone tool, but it does have some basic requirements that must be met:

30 +

31 ++ Node.js and git must be executable by npm.

32 ++ The primary npm registry, `registry.npmjs.com`, or another service that

33 + uses the registry API, is available.

34 ++ The directories that npm uses, `node_modules` (both locally and

35 + globally), exist and can be written by the current user.

36 ++ The npm cache exists, and the package tarballs within it aren't corrupt.

37 +

38 +Without all of these working properly, npm may not work properly. Many

39 +issues are often attributable to things that are outside npm's code base,

40 +so `npm doctor` confirms that the npm installation is in a good state.

41 +

42 +Also, in addition to this, there are also very many issue reports due to

43 +using old versions of npm. Since npm is constantly improving, running

44 +`npm@latest` is better than an old version.

45 +

46 +`npm doctor` verifies the following items in your environment, and if there

47 +are any recommended changes, it will display them.

48 +

49 +#### `npm ping`

50 +

51 +By default, npm installs from the primary npm registry,

52 +`registry.npmjs.org`. `npm doctor` hits a special ping endpoint within the

53 +registry. This can also be checked with `npm ping`. If this check fails,

54 +you may be using a proxy that needs to be configured, or may need to talk

55 +to your IT staff to get access over HTTPS to `registry.npmjs.org`.

56 +

57 +This check is done against whichever registry you've configured (you can

58 +see what that is by running `npm config get registry`), and if you're using

59 +a private registry that doesn't support the `/whoami` endpoint supported by

60 +the primary registry, this check may fail.

61 +

62 +#### `npm -v`

63 +

64 +While Node.js may come bundled with a particular version of npm, it's the

65 +policy of the CLI team that we recommend all users run `npm@latest` if they

66 +can. As the CLI is maintained by a small team of contributors, there are

67 +only resources for a single line of development, so npm's own long-term

68 +support releases typically only receive critical security and regression

69 +fixes. The team believes that the latest tested version of npm is almost

70 +always likely to be the most functional and defect-free version of npm.

71 +

72 +#### `node -v`

73 +

74 +For most users, in most circumstances, the best version of Node will be the

75 +latest long-term support (LTS) release. Those of you who want access to new

76 +ECMAscript features or bleeding-edge changes to Node's standard library may

77 +be running a newer version, and some may be required to run an older

78 +version of Node because of enterprise change control policies. That's OK!

79 +But in general, the npm team recommends that most users run Node.js LTS.

80 +

81 +#### `npm config get registry`

82 +

83 +You may be installing from private package registries for your project or

84 +company. That's great! Others may be following tutorials or StackOverflow

85 +questions in an effort to troubleshoot problems you may be having.

86 +Sometimes, this may entail changing the registry you're pointing at. This

87 +part of `npm doctor` just lets you, and maybe whoever's helping you with

88 +support, know that you're not using the default registry.

89 +

90 +#### `which git`

91 +

92 +While it's documented in the README, it may not be obvious that npm needs

93 +Git installed to do many of the things that it does. Also, in some cases

94 +– especially on Windows – you may have Git set up in such a way that it's

95 +not accessible via your `PATH` so that npm can find it. This check ensures

96 +that Git is available.

97 +

98 +#### Permissions checks

99 +

100 +* Your cache must be readable and writable by the user running npm.

101 +* Global package binaries must be writable by the user running npm.

102 +* Your local `node_modules` path, if you're running `npm doctor` with a

103 + project directory, must be readable and writable by the user running npm.

104 +

105 +#### Validate the checksums of cached packages

106 +

107 +When an npm package is published, the publishing process generates a

108 +checksum that npm uses at install time to verify that the package didn't

109 +get corrupted in transit. `npm doctor` uses these checksums to validate the

110 +package tarballs in your local cache (you can see where that cache is

111 +located with `npm config get cache`). In the event that there are corrupt

112 +packages in your cache, you should probably run `npm cache clean -f` and

113 +reset the cache.

114 +

115 +### Configuration

116 +

117 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

118 +<!-- automatically generated, do not edit manually -->

119 +<!-- see lib/utils/config/definitions.js -->

120 +#### `registry`

121 +

122 +* Default: "https://registry.npmjs.org/"

123 +* Type: URL

124 +

125 +The base URL of the npm registry.

126 +

127 +<!-- automatically generated, do not edit manually -->

128 +<!-- see lib/utils/config/definitions.js -->

129 +

130 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

131 +

132 +### See Also

133 +

134 +* [npm bugs](/cli/v8/commands/npm-bugs)

135 +* [npm help](/cli/v8/commands/npm-help)

136 +* [npm ping](/cli/v8/commands/npm-ping)

content/cli/v8/commands/npm-edit.md new

+62

@@ -0,0 +1,62 @@

1 +---

2 +title: npm-edit

3 +section: 1

4 +description: Edit an installed package

5 +redirect_from:

6 + - /cli/edit

7 + - /cli/edit.html

8 + - /cli/commands/edit

9 + - /cli-commands/edit

10 + - /cli-commands/edit.html

11 + - /cli-commands/npm-edit

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-edit.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm edit <pkg>

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Selects a dependency in the current project and opens the package folder in

28 +the default editor (or whatever you've configured as the npm `editor`

29 +config -- see [`npm-config`](npm-config).)

30 +

31 +After it has been edited, the package is rebuilt so as to pick up any

32 +changes in compiled packages.

33 +

34 +For instance, you can do `npm install connect` to install connect

35 +into your package, and then `npm edit connect` to make a few

36 +changes to your locally installed copy.

37 +

38 +### Configuration

39 +

40 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

41 +<!-- automatically generated, do not edit manually -->

42 +<!-- see lib/utils/config/definitions.js -->

43 +#### `editor`

44 +

45 +* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on

46 + Windows, or 'vim' on Unix systems

47 +* Type: String

48 +

49 +The command to run for `npm edit` and `npm config edit`.

50 +

51 +<!-- automatically generated, do not edit manually -->

52 +<!-- see lib/utils/config/definitions.js -->

53 +

54 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

55 +

56 +### See Also

57 +

58 +* [npm folders](/cli/v8/configuring-npm/folders)

59 +* [npm explore](/cli/v8/commands/npm-explore)

60 +* [npm install](/cli/v8/commands/npm-install)

61 +* [npm config](/cli/v8/commands/npm-config)

62 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-exec.md new

+400

@@ -0,0 +1,400 @@

1 +---

2 +title: npm-exec

3 +section: 1

4 +description: Run a command from a local or remote npm package

5 +redirect_from:

6 + - /cli/exec

7 + - /cli/exec.html

8 + - /cli/commands/exec

9 + - /cli-commands/exec

10 + - /cli-commands/exec.html

11 + - /cli-commands/npm-exec

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-exec.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm exec -- <pkg>[@<version>] [args...]

21 +npm exec --package=<pkg>[@<version>] -- <cmd> [args...]

22 +npm exec -c '<cmd> [args...]'

23 +npm exec --package=foo -c '<cmd> [args...]'

24 +npm exec [--ws] [-w <workspace-name] [args...]

25 +

26 +npx <pkg>[@<specifier>] [args...]

27 +npx -p <pkg>[@<specifier>] <cmd> [args...]

28 +npx -c '<cmd> [args...]'

29 +npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'

30 +Run without --call or positional args to open interactive subshell

31 +

32 +alias: npm x, npx

33 +

34 +common options:

35 +--package=<pkg> (may be specified multiple times)

36 +-p is a shorthand for --package only when using npx executable

37 +-c <cmd> --call=<cmd> (may not be mixed with positional arguments)

38 +```

39 +

40 +### Description

41 +

42 +This command allows you to run an arbitrary command from an npm package

43 +(either one installed locally, or fetched remotely), in a similar context

44 +as running it via `npm run`.

45 +

46 +Run without positional arguments or `--call`, this allows you to

47 +interactively run commands in the same sort of shell environment that

48 +`package.json` scripts are run. Interactive mode is not supported in CI

49 +environments when standard input is a TTY, to prevent hangs.

50 +

51 +Whatever packages are specified by the `--package` option will be

52 +provided in the `PATH` of the executed command, along with any locally

53 +installed package executables. The `--package` option may be

54 +specified multiple times, to execute the supplied command in an environment

55 +where all specified packages are available.

56 +

57 +If any requested packages are not present in the local project

58 +dependencies, then they are installed to a folder in the npm cache, which

59 +is added to the `PATH` environment variable in the executed process. A

60 +prompt is printed (which can be suppressed by providing either `--yes` or

61 +`--no`).

62 +

63 +Package names provided without a specifier will be matched with whatever

64 +version exists in the local project. Package names with a specifier will

65 +only be considered a match if they have the exact same name and version as

66 +the local dependency.

67 +

68 +If no `-c` or `--call` option is provided, then the positional arguments

69 +are used to generate the command string. If no `--package` options

70 +are provided, then npm will attempt to determine the executable name from

71 +the package specifier provided as the first positional argument according

72 +to the following heuristic:

73 +

74 +- If the package has a single entry in its `bin` field in `package.json`,

75 + or if all entries are aliases of the same command, then that command

76 + will be used.

77 +- If the package has multiple `bin` entries, and one of them matches the

78 + unscoped portion of the `name` field, then that command will be used.

79 +- If this does not result in exactly one option (either because there are

80 + no bin entries, or none of them match the `name` of the package), then

81 + `npm exec` exits with an error.

82 +

83 +To run a binary _other than_ the named binary, specify one or more

84 +`--package` options, which will prevent npm from inferring the package from

85 +the first command argument.

86 +

87 +### `npx` vs `npm exec`

88 +

89 +When run via the `npx` binary, all flags and options *must* be set prior to

90 +any positional arguments. When run via `npm exec`, a double-hyphen `--`

91 +flag can be used to suppress npm's parsing of switches and options that

92 +should be sent to the executed command.

93 +

94 +For example:

95 +

96 +```

97 +$ npx foo@latest bar --package=@npmcli/foo

98 +```

99 +

100 +In this case, npm will resolve the `foo` package name, and run the

101 +following command:

102 +

103 +```

104 +$ foo bar --package=@npmcli/foo

105 +```

106 +

107 +Since the `--package` option comes _after_ the positional arguments, it is

108 +treated as an argument to the executed command.

109 +

110 +In contrast, due to npm's argument parsing logic, running this command is

111 +different:

112 +

113 +```

114 +$ npm exec foo@latest bar --package=@npmcli/foo

115 +```

116 +

117 +In this case, npm will parse the `--package` option first, resolving the

118 +`@npmcli/foo` package. Then, it will execute the following command in that

119 +context:

120 +

121 +```

122 +$ foo@latest bar

123 +```

124 +

125 +The double-hyphen character is recommended to explicitly tell npm to stop

126 +parsing command line options and switches. The following command would

127 +thus be equivalent to the `npx` command above:

128 +

129 +```

130 +$ npm exec -- foo@latest bar --package=@npmcli/foo

131 +```

132 +

133 +### Configuration

134 +

135 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

136 +<!-- automatically generated, do not edit manually -->

137 +<!-- see lib/utils/config/definitions.js -->

138 +#### `package`

139 +

140 +* Default:

141 +* Type: String (can be set multiple times)

142 +

143 +The package to install for [`npm exec`](/cli/v8/commands/npm-exec)

144 +

145 +<!-- automatically generated, do not edit manually -->

146 +<!-- see lib/utils/config/definitions.js -->

147 +

148 +#### `call`

149 +

150 +* Default: ""

151 +* Type: String

152 +

153 +Optional companion option for `npm exec`, `npx` that allows for specifying a

154 +custom command to be run along with the installed packages.

155 +

156 +```bash

157 +npm exec --package yo --package generator-node --call "yo node"

158 +```

159 +

160 +

161 +<!-- automatically generated, do not edit manually -->

162 +<!-- see lib/utils/config/definitions.js -->

163 +

164 +#### `workspace`

165 +

166 +* Default:

167 +* Type: String (can be set multiple times)

168 +

169 +Enable running a command in the context of the configured workspaces of the

170 +current project while filtering by running only the workspaces defined by

171 +this configuration option.

172 +

173 +Valid values for the `workspace` config are either:

174 +

175 +* Workspace names

176 +* Path to a workspace directory

177 +* Path to a parent workspace directory (will result in selecting all

178 + workspaces within that folder)

179 +

180 +When set for the `npm init` command, this may be set to the folder of a

181 +workspace which does not yet exist, to create the folder and set it up as a

182 +brand new workspace within the project.

183 +

184 +This value is not exported to the environment for child processes.

185 +

186 +<!-- automatically generated, do not edit manually -->

187 +<!-- see lib/utils/config/definitions.js -->

188 +

189 +#### `workspaces`

190 +

191 +* Default: null

192 +* Type: null or Boolean

193 +

194 +Set to true to run the command in the context of **all** configured

195 +workspaces.

196 +

197 +Explicitly setting this to false will cause commands like `install` to

198 +ignore workspaces altogether. When not set explicitly:

199 +

200 +- Commands that operate on the `node_modules` tree (install, update, etc.)

201 +will link workspaces into the `node_modules` folder. - Commands that do

202 +other things (test, exec, publish, etc.) will operate on the root project,

203 +_unless_ one or more workspaces are specified in the `workspace` config.

204 +

205 +This value is not exported to the environment for child processes.

206 +

207 +<!-- automatically generated, do not edit manually -->

208 +<!-- see lib/utils/config/definitions.js -->

209 +

210 +#### `include-workspace-root`

211 +

212 +* Default: false

213 +* Type: Boolean

214 +

215 +Include the workspace root when workspaces are enabled for a command.

216 +

217 +When false, specifying individual workspaces via the `workspace` config, or

218 +all workspaces via the `workspaces` flag, will cause npm to operate only on

219 +the specified workspaces, and not on the root project.

220 +

221 +<!-- automatically generated, do not edit manually -->

222 +<!-- see lib/utils/config/definitions.js -->

223 +

224 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

225 +

226 +### Examples

227 +

228 +Run the version of `tap` in the local dependencies, with the provided

229 +arguments:

230 +

231 +```

232 +$ npm exec -- tap --bail test/foo.js

233 +$ npx tap --bail test/foo.js

234 +```

235 +

236 +Run a command _other than_ the command whose name matches the package name

237 +by specifying a `--package` option:

238 +

239 +```

240 +$ npm exec --package=foo -- bar --bar-argument

241 +# ~ or ~

242 +$ npx --package=foo bar --bar-argument

243 +```

244 +

245 +Run an arbitrary shell script, in the context of the current project:

246 +

247 +```

248 +$ npm x -c 'eslint && say "hooray, lint passed"'

249 +$ npx -c 'eslint && say "hooray, lint passed"'

250 +```

251 +

252 +### Workspaces support

253 +

254 +You may use the `workspace` or `workspaces` configs in order to run an

255 +arbitrary command from an npm package (either one installed locally, or fetched

256 +remotely) in the context of the specified workspaces.

257 +If no positional argument or `--call` option is provided, it will open an

258 +interactive subshell in the context of each of these configured workspaces one

259 +at a time.

260 +

261 +Given a project with configured workspaces, e.g:

262 +

263 +```

264 +.

265 ++-- package.json

266 +`-- packages

267 + +-- a

268 + | `-- package.json

269 + +-- b

270 + | `-- package.json

271 + `-- c

272 + `-- package.json

273 +```

274 +

275 +Assuming the workspace configuration is properly set up at the root level

276 +`package.json` file. e.g:

277 +

278 +```

279 +{

280 + "workspaces": [ "./packages/*" ]

281 +}

282 +```

283 +

284 +You can execute an arbitrary command from a package in the context of each of

285 +the configured workspaces when using the `workspaces` configuration options,

286 +in this example we're using **eslint** to lint any js file found within each

287 +workspace folder:

288 +

289 +```

290 +npm exec --ws -- eslint ./*.js

291 +```

292 +

293 +#### Filtering workspaces

294 +

295 +It's also possible to execute a command in a single workspace using the

296 +`workspace` config along with a name or directory path:

297 +

298 +```

299 +npm exec --workspace=a -- eslint ./*.js

300 +```

301 +

302 +The `workspace` config can also be specified multiple times in order to run a

303 +specific script in the context of multiple workspaces. When defining values for

304 +the `workspace` config in the command line, it also possible to use `-w` as a

305 +shorthand, e.g:

306 +

307 +```

308 +npm exec -w a -w b -- eslint ./*.js

309 +```

310 +

311 +This last command will run the `eslint` command in both `./packages/a` and

312 +`./packages/b` folders.

313 +

314 +### Compatibility with Older npx Versions

315 +

316 +The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx`

317 +package deprecated at that time. `npx` uses the `npm exec`

318 +command instead of a separate argument parser and install process, with

319 +some affordances to maintain backwards compatibility with the arguments it

320 +accepted in previous versions.

321 +

322 +This resulted in some shifts in its functionality:

323 +

324 +- Any `npm` config value may be provided.

325 +- To prevent security and user-experience problems from mistyping package

326 + names, `npx` prompts before installing anything. Suppress this

327 + prompt with the `-y` or `--yes` option.

328 +- The `--no-install` option is deprecated, and will be converted to `--no`.

329 +- Shell fallback functionality is removed, as it is not advisable.

330 +- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand

331 + for `--package` in npx. This is maintained, but only for the `npx`

332 + executable.

333 +- The `--ignore-existing` option is removed. Locally installed bins are

334 + always present in the executed process `PATH`.

335 +- The `--npm` option is removed. `npx` will always use the `npm` it ships

336 + with.

337 +- The `--node-arg` and `-n` options are removed.

338 +- The `--always-spawn` option is redundant, and thus removed.

339 +- The `--shell` option is replaced with `--script-shell`, but maintained

340 + in the `npx` executable for backwards compatibility.

341 +

342 +### A note on caching

343 +

344 +The npm cli utilizes its internal package cache when using the package

345 +name specified. You can use the following to change how and when the

346 +cli uses this cache. See [`npm cache`](/cli/v8/commands/npm-cache) for more on

347 +how the cache works.

348 +

349 +#### prefer-online

350 +

351 +Forces staleness checks for packages, making the cli look for updates

352 +immediately even if the package is already in the cache.

353 +

354 +#### prefer-offline

355 +

356 +Bypasses staleness checks for packages. Missing data will still be

357 +requested from the server. To force full offline mode, use `offline`.

358 +

359 +#### offline

360 +

361 +Forces full offline mode. Any packages not locally cached will result in

362 +an error.

363 +

364 +#### workspace

365 +

366 +* Default:

367 +* Type: String (can be set multiple times)

368 +

369 +Enable running a command in the context of the configured workspaces of the

370 +current project while filtering by running only the workspaces defined by

371 +this configuration option.

372 +

373 +Valid values for the `workspace` config are either:

374 +

375 +* Workspace names

376 +* Path to a workspace directory

377 +* Path to a parent workspace directory (will result to selecting all of the

378 + nested workspaces)

379 +

380 +This value is not exported to the environment for child processes.

381 +

382 +#### workspaces

383 +

384 +* Alias: `--ws`

385 +* Type: Boolean

386 +* Default: `false`

387 +

388 +Run scripts in the context of all configured workspaces for the current

389 +project.

390 +

391 +### See Also

392 +

393 +* [npm run-script](/cli/v8/commands/npm-run-script)

394 +* [npm scripts](/cli/v8/using-npm/scripts)

395 +* [npm test](/cli/v8/commands/npm-test)

396 +* [npm start](/cli/v8/commands/npm-start)

397 +* [npm restart](/cli/v8/commands/npm-restart)

398 +* [npm stop](/cli/v8/commands/npm-stop)

399 +* [npm config](/cli/v8/commands/npm-config)

400 +* [npm workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-explain.md new

+122

@@ -0,0 +1,122 @@

1 +---

2 +title: npm-explain

3 +section: 1

4 +description: Explain installed packages

5 +redirect_from:

6 + - /cli/explain

7 + - /cli/explain.html

8 + - /cli/commands/explain

9 + - /cli-commands/explain

10 + - /cli-commands/explain.html

11 + - /cli-commands/npm-explain

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-explain.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm explain <folder | specifier>

21 +

22 +alias: why

23 +```

24 +

25 +### Description

26 +

27 +This command will print the chain of dependencies causing a given package

28 +to be installed in the current project.

29 +

30 +Positional arguments can be either folders within `node_modules`, or

31 +`name@version-range` specifiers, which will select the dependency

32 +relationships to explain.

33 +

34 +For example, running `npm explain glob` within npm's source tree will show:

35 +

36 +```bash

37 +glob@7.1.6

38 +node_modules/glob

39 + glob@"^7.1.4" from the root project

40 +

41 +glob@7.1.1 dev

42 +node_modules/tacks/node_modules/glob

43 + glob@"^7.0.5" from rimraf@2.6.2

44 + node_modules/tacks/node_modules/rimraf

45 + rimraf@"^2.6.2" from tacks@1.3.0

46 + node_modules/tacks

47 + dev tacks@"^1.3.0" from the root project

48 +```

49 +

50 +To explain just the package residing at a specific folder, pass that as the

51 +argument to the command. This can be useful when trying to figure out

52 +exactly why a given dependency is being duplicated to satisfy conflicting

53 +version requirements within the project.

54 +

55 +```bash

56 +$ npm explain node_modules/nyc/node_modules/find-up

57 +find-up@3.0.0 dev

58 +node_modules/nyc/node_modules/find-up

59 + find-up@"^3.0.0" from nyc@14.1.1

60 + node_modules/nyc

61 + nyc@"^14.1.1" from tap@14.10.8

62 + node_modules/tap

63 + dev tap@"^14.10.8" from the root project

64 +```

65 +

66 +### Configuration

67 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

68 +<!-- automatically generated, do not edit manually -->

69 +<!-- see lib/utils/config/definitions.js -->

70 +#### `json`

71 +

72 +* Default: false

73 +* Type: Boolean

74 +

75 +Whether or not to output JSON data, rather than the normal output.

76 +

77 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

78 + saving them to your `package.json`.

79 +

80 +Not supported by all npm commands.

81 +

82 +<!-- automatically generated, do not edit manually -->

83 +<!-- see lib/utils/config/definitions.js -->

84 +

85 +#### `workspace`

86 +

87 +* Default:

88 +* Type: String (can be set multiple times)

89 +

90 +Enable running a command in the context of the configured workspaces of the

91 +current project while filtering by running only the workspaces defined by

92 +this configuration option.

93 +

94 +Valid values for the `workspace` config are either:

95 +

96 +* Workspace names

97 +* Path to a workspace directory

98 +* Path to a parent workspace directory (will result in selecting all

99 + workspaces within that folder)

100 +

101 +When set for the `npm init` command, this may be set to the folder of a

102 +workspace which does not yet exist, to create the folder and set it up as a

103 +brand new workspace within the project.

104 +

105 +This value is not exported to the environment for child processes.

106 +

107 +<!-- automatically generated, do not edit manually -->

108 +<!-- see lib/utils/config/definitions.js -->

109 +

110 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

111 +

112 +### See Also

113 +

114 +* [npm config](/cli/v8/commands/npm-config)

115 +* [npmrc](/cli/v8/configuring-npm/npmrc)

116 +* [npm folders](/cli/v8/configuring-npm/folders)

117 +* [npm ls](/cli/v8/commands/npm-ls)

118 +* [npm install](/cli/v8/commands/npm-install)

119 +* [npm link](/cli/v8/commands/npm-link)

120 +* [npm prune](/cli/v8/commands/npm-prune)

121 +* [npm outdated](/cli/v8/commands/npm-outdated)

122 +* [npm update](/cli/v8/commands/npm-update)

content/cli/v8/commands/npm-explore.md new

+65

@@ -0,0 +1,65 @@

1 +---

2 +title: npm-explore

3 +section: 1

4 +description: Browse an installed package

5 +redirect_from:

6 + - /cli/explore

7 + - /cli/explore.html

8 + - /cli/commands/explore

9 + - /cli-commands/explore

10 + - /cli-commands/explore.html

11 + - /cli-commands/npm-explore

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-explore.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm explore <pkg> [ -- <command>]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Spawn a subshell in the directory of the installed package specified.

28 +

29 +If a command is specified, then it is run in the subshell, which then

30 +immediately terminates.

31 +

32 +This is particularly handy in the case of git submodules in the

33 +`node_modules` folder:

34 +

35 +```bash

36 +npm explore some-dependency -- git pull origin master

37 +```

38 +

39 +Note that the package is *not* automatically rebuilt afterwards, so be

40 +sure to use `npm rebuild <pkg>` if you make any changes.

41 +

42 +### Configuration

43 +

44 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

45 +<!-- automatically generated, do not edit manually -->

46 +<!-- see lib/utils/config/definitions.js -->

47 +#### `shell`

48 +

49 +* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe" on

50 + Windows

51 +* Type: String

52 +

53 +The shell to run for the `npm explore` command.

54 +

55 +<!-- automatically generated, do not edit manually -->

56 +<!-- see lib/utils/config/definitions.js -->

57 +

58 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

59 +

60 +### See Also

61 +

62 +* [npm folders](/cli/v8/configuring-npm/folders)

63 +* [npm edit](/cli/v8/commands/npm-edit)

64 +* [npm rebuild](/cli/v8/commands/npm-rebuild)

65 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/commands/npm-find-dupes.md new

+242

@@ -0,0 +1,242 @@

1 +---

2 +title: npm-find-dupes

3 +section: 1

4 +description: Find duplication in the package tree

5 +redirect_from:

6 + - /cli/find-dupes

7 + - /cli/find-dupes.html

8 + - /cli/commands/find-dupes

9 + - /cli-commands/find-dupes

10 + - /cli-commands/find-dupes.html

11 + - /cli-commands/npm-find-dupes

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-find-dupes.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm find-dupes

21 +```

22 +

23 +### Description

24 +

25 +Runs `npm dedupe` in `--dry-run` mode, making npm only output the

26 +duplications, without actually changing the package tree.

27 +

28 +### Configuration

29 +

30 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

31 +<!-- automatically generated, do not edit manually -->

32 +<!-- see lib/utils/config/definitions.js -->

33 +#### `global-style`

34 +

35 +* Default: false

36 +* Type: Boolean

37 +

38 +Causes npm to install the package into your local `node_modules` folder with

39 +the same layout it uses with the global `node_modules` folder. Only your

40 +direct dependencies will show in `node_modules` and everything they depend

41 +on will be flattened in their `node_modules` folders. This obviously will

42 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

43 +will be preferred.

44 +

45 +<!-- automatically generated, do not edit manually -->

46 +<!-- see lib/utils/config/definitions.js -->

47 +

48 +#### `legacy-bundling`

49 +

50 +* Default: false

51 +* Type: Boolean

52 +

53 +Causes npm to install the package such that versions of npm prior to 1.4,

54 +such as the one included with node 0.8, can install the package. This

55 +eliminates all automatic deduping. If used with `global-style` this option

56 +will be preferred.

57 +

58 +<!-- automatically generated, do not edit manually -->

59 +<!-- see lib/utils/config/definitions.js -->

60 +

61 +#### `strict-peer-deps`

62 +

63 +* Default: false

64 +* Type: Boolean

65 +

66 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

67 +conflicting `peerDependencies` will be treated as an install failure, even

68 +if npm could reasonably guess the appropriate resolution based on non-peer

69 +dependency relationships.

70 +

71 +By default, conflicting `peerDependencies` deep in the dependency graph will

72 +be resolved using the nearest non-peer dependency specification, even if

73 +doing so will result in some packages receiving a peer dependency outside

74 +the range set in their package's `peerDependencies` object.

75 +

76 +When such and override is performed, a warning is printed, explaining the

77 +conflict and the packages involved. If `--strict-peer-deps` is set, then

78 +this warning is treated as a failure.

79 +

80 +<!-- automatically generated, do not edit manually -->

81 +<!-- see lib/utils/config/definitions.js -->

82 +

83 +#### `package-lock`

84 +

85 +* Default: true

86 +* Type: Boolean

87 +

88 +If set to false, then ignore `package-lock.json` files when installing. This

89 +will also prevent _writing_ `package-lock.json` if `save` is true.

90 +

91 +When package package-locks are disabled, automatic pruning of extraneous

92 +modules will also be disabled. To remove extraneous modules with

93 +package-locks disabled use `npm prune`.

94 +

95 +<!-- automatically generated, do not edit manually -->

96 +<!-- see lib/utils/config/definitions.js -->

97 +

98 +#### `omit`

99 +

100 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

101 + 'production', otherwise empty.

102 +* Type: "dev", "optional", or "peer" (can be set multiple times)

103 +

104 +Dependency types to omit from the installation tree on disk.

105 +

106 +Note that these dependencies _are_ still resolved and added to the

107 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

108 +physically installed on disk.

109 +

110 +If a package type appears in both the `--include` and `--omit` lists, then

111 +it will be included.

112 +

113 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

114 +variable will be set to `'production'` for all lifecycle scripts.

115 +

116 +<!-- automatically generated, do not edit manually -->

117 +<!-- see lib/utils/config/definitions.js -->

118 +

119 +#### `ignore-scripts`

120 +

121 +* Default: false

122 +* Type: Boolean

123 +

124 +If true, npm does not run scripts specified in package.json files.

125 +

126 +Note that commands explicitly intended to run a particular script, such as

127 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

128 +will still run their intended script if `ignore-scripts` is set, but they

129 +will *not* run any pre- or post-scripts.

130 +

131 +<!-- automatically generated, do not edit manually -->

132 +<!-- see lib/utils/config/definitions.js -->

133 +

134 +#### `audit`

135 +

136 +* Default: true

137 +* Type: Boolean

138 +

139 +When "true" submit audit reports alongside the current npm command to the

140 +default registry and all registries configured for scopes. See the

141 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

142 +submitted.

143 +

144 +<!-- automatically generated, do not edit manually -->

145 +<!-- see lib/utils/config/definitions.js -->

146 +

147 +#### `bin-links`

148 +

149 +* Default: true

150 +* Type: Boolean

151 +

152 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

153 +executables.

154 +

155 +Set to false to have it not do this. This can be used to work around the

156 +fact that some file systems don't support symlinks, even on ostensibly Unix

157 +systems.

158 +

159 +<!-- automatically generated, do not edit manually -->

160 +<!-- see lib/utils/config/definitions.js -->

161 +

162 +#### `fund`

163 +

164 +* Default: true

165 +* Type: Boolean

166 +

167 +When "true" displays the message at the end of each `npm install`

168 +acknowledging the number of dependencies looking for funding. See [`npm

169 +fund`](/cli/v8/commands/npm-fund) for details.

170 +

171 +<!-- automatically generated, do not edit manually -->

172 +<!-- see lib/utils/config/definitions.js -->

173 +

174 +#### `workspace`

175 +

176 +* Default:

177 +* Type: String (can be set multiple times)

178 +

179 +Enable running a command in the context of the configured workspaces of the

180 +current project while filtering by running only the workspaces defined by

181 +this configuration option.

182 +

183 +Valid values for the `workspace` config are either:

184 +

185 +* Workspace names

186 +* Path to a workspace directory

187 +* Path to a parent workspace directory (will result in selecting all

188 + workspaces within that folder)

189 +

190 +When set for the `npm init` command, this may be set to the folder of a

191 +workspace which does not yet exist, to create the folder and set it up as a

192 +brand new workspace within the project.

193 +

194 +This value is not exported to the environment for child processes.

195 +

196 +<!-- automatically generated, do not edit manually -->

197 +<!-- see lib/utils/config/definitions.js -->

198 +

199 +#### `workspaces`

200 +

201 +* Default: null

202 +* Type: null or Boolean

203 +

204 +Set to true to run the command in the context of **all** configured

205 +workspaces.

206 +

207 +Explicitly setting this to false will cause commands like `install` to

208 +ignore workspaces altogether. When not set explicitly:

209 +

210 +- Commands that operate on the `node_modules` tree (install, update, etc.)

211 +will link workspaces into the `node_modules` folder. - Commands that do

212 +other things (test, exec, publish, etc.) will operate on the root project,

213 +_unless_ one or more workspaces are specified in the `workspace` config.

214 +

215 +This value is not exported to the environment for child processes.

216 +

217 +<!-- automatically generated, do not edit manually -->

218 +<!-- see lib/utils/config/definitions.js -->

219 +

220 +#### `include-workspace-root`

221 +

222 +* Default: false

223 +* Type: Boolean

224 +

225 +Include the workspace root when workspaces are enabled for a command.

226 +

227 +When false, specifying individual workspaces via the `workspace` config, or

228 +all workspaces via the `workspaces` flag, will cause npm to operate only on

229 +the specified workspaces, and not on the root project.

230 +

231 +<!-- automatically generated, do not edit manually -->

232 +<!-- see lib/utils/config/definitions.js -->

233 +

234 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

235 +

236 +### See Also

237 +

238 +* [npm dedupe](/cli/v8/commands/npm-dedupe)

239 +* [npm ls](/cli/v8/commands/npm-ls)

240 +* [npm update](/cli/v8/commands/npm-update)

241 +* [npm install](/cli/v8/commands/npm-install)

242 +

content/cli/v8/commands/npm-fund.md new

+165

@@ -0,0 +1,165 @@

1 +---

2 +title: npm-fund

3 +section: 1

4 +description: Retrieve funding information

5 +redirect_from:

6 + - /cli/fund

7 + - /cli/fund.html

8 + - /cli/commands/fund

9 + - /cli-commands/fund

10 + - /cli-commands/fund.html

11 + - /cli-commands/npm-fund

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-fund.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm fund [<pkg>]

21 +npm fund [-w <workspace-name>]

22 +```

23 +

24 +### Description

25 +

26 +This command retrieves information on how to fund the dependencies of a

27 +given project. If no package name is provided, it will list all

28 +dependencies that are looking for funding in a tree structure, listing the

29 +type of funding and the url to visit. If a package name is provided then it

30 +tries to open its funding url using the `--browser` config param; if there

31 +are multiple funding sources for the package, the user will be instructed

32 +to pass the `--which` option to disambiguate.

33 +

34 +The list will avoid duplicated entries and will stack all packages that

35 +share the same url as a single entry. Thus, the list does not have the same

36 +shape of the output from `npm ls`.

37 +

38 +#### Example

39 +

40 +### Workspaces support

41 +

42 +It's possible to filter the results to only include a single workspace and its

43 +dependencies using the `workspace` config option.

44 +

45 +#### Example:

46 +

47 +Here's an example running `npm fund` in a project with a configured

48 +workspace `a`:

49 +

50 +```bash

51 +$ npm fund

52 +test-workspaces-fund@1.0.0

53 ++-- https://example.com/a

54 +| | `-- a@1.0.0

55 +| `-- https://example.com/maintainer

56 +| `-- foo@1.0.0

57 ++-- https://example.com/npmcli-funding

58 +| `-- @npmcli/test-funding

59 +`-- https://example.com/org

60 + `-- bar@2.0.0

61 +```

62 +

63 +And here is an example of the expected result when filtering only by

64 +a specific workspace `a` in the same project:

65 +

66 +```bash

67 +$ npm fund -w a

68 +test-workspaces-fund@1.0.0

69 +`-- https://example.com/a

70 + | `-- a@1.0.0

71 + `-- https://example.com/maintainer

72 + `-- foo@2.0.0

73 +```

74 +

75 +### Configuration

76 +

77 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

78 +<!-- automatically generated, do not edit manually -->

79 +<!-- see lib/utils/config/definitions.js -->

80 +#### `json`

81 +

82 +* Default: false

83 +* Type: Boolean

84 +

85 +Whether or not to output JSON data, rather than the normal output.

86 +

87 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

88 + saving them to your `package.json`.

89 +

90 +Not supported by all npm commands.

91 +

92 +<!-- automatically generated, do not edit manually -->

93 +<!-- see lib/utils/config/definitions.js -->

94 +

95 +#### `browser`

96 +

97 +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`

98 +* Type: null, Boolean, or String

99 +

100 +The browser that is called by npm commands to open websites.

101 +

102 +Set to `false` to suppress browser behavior and instead print urls to

103 +terminal.

104 +

105 +Set to `true` to use default system URL opener.

106 +

107 +<!-- automatically generated, do not edit manually -->

108 +<!-- see lib/utils/config/definitions.js -->

109 +

110 +#### `unicode`

111 +

112 +* Default: false on windows, true on mac/unix systems with a unicode locale,

113 + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables.

114 +* Type: Boolean

115 +

116 +When set to true, npm uses unicode characters in the tree output. When

117 +false, it uses ascii characters instead of unicode glyphs.

118 +

119 +<!-- automatically generated, do not edit manually -->

120 +<!-- see lib/utils/config/definitions.js -->

121 +

122 +#### `workspace`

123 +

124 +* Default:

125 +* Type: String (can be set multiple times)

126 +

127 +Enable running a command in the context of the configured workspaces of the

128 +current project while filtering by running only the workspaces defined by

129 +this configuration option.

130 +

131 +Valid values for the `workspace` config are either:

132 +

133 +* Workspace names

134 +* Path to a workspace directory

135 +* Path to a parent workspace directory (will result in selecting all

136 + workspaces within that folder)

137 +

138 +When set for the `npm init` command, this may be set to the folder of a

139 +workspace which does not yet exist, to create the folder and set it up as a

140 +brand new workspace within the project.

141 +

142 +This value is not exported to the environment for child processes.

143 +

144 +<!-- automatically generated, do not edit manually -->

145 +<!-- see lib/utils/config/definitions.js -->

146 +

147 +#### `which`

148 +

149 +* Default: null

150 +* Type: null or Number

151 +

152 +If there are multiple funding sources, which 1-indexed source URL to open.

153 +

154 +<!-- automatically generated, do not edit manually -->

155 +<!-- see lib/utils/config/definitions.js -->

156 +

157 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

158 +

159 +## See Also

160 +

161 +* [npm install](/cli/v8/commands/npm-install)

162 +* [npm docs](/cli/v8/commands/npm-docs)

163 +* [npm ls](/cli/v8/commands/npm-ls)

164 +* [npm config](/cli/v8/commands/npm-config)

165 +* [npm workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-help-search.md new

+56

@@ -0,0 +1,56 @@

1 +---

2 +title: npm-help-search

3 +section: 1

4 +description: Search npm help documentation

5 +redirect_from:

6 + - /cli/help-search

7 + - /cli/help-search.html

8 + - /cli/commands/help-search

9 + - /cli-commands/help-search

10 + - /cli-commands/help-search.html

11 + - /cli-commands/npm-help-search

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-help-search.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm help-search <text>

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +This command will search the npm markdown documentation files for the terms

28 +provided, and then list the results, sorted by relevance.

29 +

30 +If only one result is found, then it will show that help topic.

31 +

32 +If the argument to `npm help` is not a known help topic, then it will call

33 +`help-search`. It is rarely if ever necessary to call this command

34 +directly.

35 +

36 +### Configuration

37 +

38 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

39 +<!-- automatically generated, do not edit manually -->

40 +<!-- see lib/utils/config/definitions.js -->

41 +#### `long`

42 +

43 +* Default: false

44 +* Type: Boolean

45 +

46 +Show extended information in `ls`, `search`, and `help-search`.

47 +

48 +<!-- automatically generated, do not edit manually -->

49 +<!-- see lib/utils/config/definitions.js -->

50 +

51 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

52 +

53 +### See Also

54 +

55 +* [npm](/cli/v8/commands/npm)

56 +* [npm help](/cli/v8/commands/npm-help)

content/cli/v8/commands/npm-help.md new

+60

@@ -0,0 +1,60 @@

1 +---

2 +title: npm-help

3 +section: 1

4 +description: Get help on npm

5 +redirect_from:

6 + - /cli/help

7 + - /cli/help.html

8 + - /cli/commands/help

9 + - /cli-commands/help

10 + - /cli-commands/help.html

11 + - /cli-commands/npm-help

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-help.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm help <term> [<terms..>]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +If supplied a topic, then show the appropriate documentation page.

28 +

29 +If the topic does not exist, or if multiple terms are provided, then npm

30 +will run the `help-search` command to find a match. Note that, if

31 +`help-search` finds a single subject, then it will run `help` on that

32 +topic, so unique matches are equivalent to specifying a topic name.

33 +

34 +### Configuration

35 +

36 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

37 +<!-- automatically generated, do not edit manually -->

38 +<!-- see lib/utils/config/definitions.js -->

39 +#### `viewer`

40 +

41 +* Default: "man" on Posix, "browser" on Windows

42 +* Type: String

43 +

44 +The program to use to view help content.

45 +

46 +Set to `"browser"` to view html help content in the default web browser.

47 +

48 +<!-- automatically generated, do not edit manually -->

49 +<!-- see lib/utils/config/definitions.js -->

50 +

51 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

52 +

53 +### See Also

54 +

55 +* [npm](/cli/v8/commands/npm)

56 +* [npm folders](/cli/v8/configuring-npm/folders)

57 +* [npm config](/cli/v8/commands/npm-config)

58 +* [npmrc](/cli/v8/configuring-npm/npmrc)

59 +* [package.json](/cli/v8/configuring-npm/package-json)

60 +* [npm help-search](/cli/v8/commands/npm-help-search)

content/cli/v8/commands/npm-hook.md new

+129

@@ -0,0 +1,129 @@

1 +---

2 +title: npm-hook

3 +section: 1

4 +description: Manage registry hooks

5 +redirect_from:

6 + - /cli/hook

7 + - /cli/hook.html

8 + - /cli/commands/hook

9 + - /cli-commands/hook

10 + - /cli-commands/hook.html

11 + - /cli-commands/npm-hook

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-hook.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm hook ls [pkg]

21 +npm hook add <entity> <url> <secret>

22 +npm hook update <id> <url> [secret]

23 +npm hook rm <id>

24 +```

25 +

26 +Note: This command is unaware of workspaces.

27 +

28 +### Description

29 +

30 +Allows you to manage [npm

31 +hooks](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm),

32 +including adding, removing, listing, and updating.

33 +

34 +Hooks allow you to configure URL endpoints that will be notified whenever a

35 +change happens to any of the supported entity types. Three different types

36 +of entities can be watched by hooks: packages, owners, and scopes.

37 +

38 +To create a package hook, simply reference the package name.

39 +

40 +To create an owner hook, prefix the owner name with `~` (as in,

41 +`~youruser`).

42 +

43 +To create a scope hook, prefix the scope name with `@` (as in,

44 +`@yourscope`).

45 +

46 +The hook `id` used by `update` and `rm` are the IDs listed in `npm hook ls`

47 +for that particular hook.

48 +

49 +The shared secret will be sent along to the URL endpoint so you can verify

50 +the request came from your own configured hook.

51 +

52 +### Example

53 +

54 +Add a hook to watch a package for changes:

55 +

56 +```bash

57 +$ npm hook add lodash https://example.com/ my-shared-secret

58 +```

59 +

60 +Add a hook to watch packages belonging to the user `substack`:

61 +

62 +```bash

63 +$ npm hook add ~substack https://example.com/ my-shared-secret

64 +```

65 +

66 +Add a hook to watch packages in the scope `@npm`

67 +

68 +```bash

69 +$ npm hook add @npm https://example.com/ my-shared-secret

70 +```

71 +

72 +List all your active hooks:

73 +

74 +```bash

75 +$ npm hook ls

76 +```

77 +

78 +List your active hooks for the `lodash` package:

79 +

80 +```bash

81 +$ npm hook ls lodash

82 +```

83 +

84 +Update an existing hook's url:

85 +

86 +```bash

87 +$ npm hook update id-deadbeef https://my-new-website.here/

88 +```

89 +

90 +Remove a hook:

91 +

92 +```bash

93 +$ npm hook rm id-deadbeef

94 +```

95 +

96 +### Configuration

97 +

98 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

99 +<!-- automatically generated, do not edit manually -->

100 +<!-- see lib/utils/config/definitions.js -->

101 +#### `registry`

102 +

103 +* Default: "https://registry.npmjs.org/"

104 +* Type: URL

105 +

106 +The base URL of the npm registry.

107 +

108 +<!-- automatically generated, do not edit manually -->

109 +<!-- see lib/utils/config/definitions.js -->

110 +

111 +#### `otp`

112 +

113 +* Default: null

114 +* Type: null or String

115 +

116 +This is a one-time password from a two-factor authenticator. It's needed

117 +when publishing or changing package permissions with `npm access`.

118 +

119 +If not set, and a registry response fails with a challenge for a one-time

120 +password, npm will prompt on the command line for one.

121 +

122 +<!-- automatically generated, do not edit manually -->

123 +<!-- see lib/utils/config/definitions.js -->

124 +

125 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

126 +

127 +### See Also

128 +

129 +* ["Introducing Hooks" blog post](https://blog.npmjs.org/post/145260155635/introducing-hooks-get-notifications-of-npm)

content/cli/v8/commands/npm-init.md new

+269

@@ -0,0 +1,269 @@

1 +---

2 +title: npm-init

3 +section: 1

4 +description: Create a package.json file

5 +redirect_from:

6 + - /cli/init

7 + - /cli/init.html

8 + - /cli/commands/init

9 + - /cli-commands/init

10 + - /cli-commands/init.html

11 + - /cli-commands/npm-init

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-init.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm init [--yes|-y|--scope]

21 +npm init <@scope> (same as `npm exec <@scope>/create`)

22 +npm init [<@scope>/]<name> (same as `npm exec [<@scope>/]create-<name>`)

23 +npm init [-w <dir>] [args...]

24 +```

25 +

26 +### Description

27 +

28 +`npm init <initializer>` can be used to set up a new or existing npm

29 +package.

30 +

31 +`initializer` in this case is an npm package named `create-<initializer>`,

32 +which will be installed by [`npm-exec`](/cli/v8/commands/npm-exec), and then have its

33 +main bin executed -- presumably creating or updating `package.json` and

34 +running any other initialization-related operations.

35 +

36 +The init command is transformed to a corresponding `npm exec` operation as

37 +follows:

38 +

39 +* `npm init foo` -> `npm exec create-foo`

40 +* `npm init @usr/foo` -> `npm exec @usr/create-foo`

41 +* `npm init @usr` -> `npm exec @usr/create`

42 +

43 +If the initializer is omitted (by just calling `npm init`), init will fall

44 +back to legacy init behavior. It will ask you a bunch of questions, and

45 +then write a package.json for you. It will attempt to make reasonable

46 +guesses based on existing fields, dependencies, and options selected. It is

47 +strictly additive, so it will keep any fields and values that were already

48 +set. You can also use `-y`/`--yes` to skip the questionnaire altogether. If

49 +you pass `--scope`, it will create a scoped package.

50 +

51 +#### Forwarding additional options

52 +

53 +Any additional options will be passed directly to the command, so `npm init

54 +foo -- --hello` will map to `npm exec -- create-foo --hello`.

55 +

56 +To better illustrate how options are forwarded, here's a more evolved

57 +example showing options passed to both the **npm cli** and a create package,

58 +both following commands are equivalent:

59 +

60 +- `npm init foo -y --registry=<url> -- --hello -a`

61 +- `npm exec -y --registry=<url> -- create-foo --hello -a`

62 +

63 +### Examples

64 +

65 +Create a new React-based project using

66 +[`create-react-app`](https://npm.im/create-react-app):

67 +

68 +```bash

69 +$ npm init react-app ./my-react-app

70 +```

71 +

72 +Create a new `esm`-compatible package using

73 +[`create-esm`](https://npm.im/create-esm):

74 +

75 +```bash

76 +$ mkdir my-esm-lib && cd my-esm-lib

77 +$ npm init esm --yes

78 +```

79 +

80 +Generate a plain old package.json using legacy init:

81 +

82 +```bash

83 +$ mkdir my-npm-pkg && cd my-npm-pkg

84 +$ git init

85 +$ npm init

86 +```

87 +

88 +Generate it without having it ask any questions:

89 +

90 +```bash

91 +$ npm init -y

92 +```

93 +

94 +### Workspaces support

95 +

96 +It's possible to create a new workspace within your project by using the

97 +`workspace` config option. When using `npm init -w <dir>` the cli will

98 +create the folders and boilerplate expected while also adding a reference

99 +to your project `package.json` `"workspaces": []` property in order to make

100 +sure that new generated **workspace** is properly set up as such.

101 +

102 +Given a project with no workspaces, e.g:

103 +

104 +```

105 +.

106 ++-- package.json

107 +```

108 +

109 +You may generate a new workspace using the legacy init:

110 +

111 +```bash

112 +$ npm init -w packages/a

113 +```

114 +

115 +That will generate a new folder and `package.json` file, while also updating

116 +your top-level `package.json` to add the reference to this new workspace:

117 +

118 +```

119 +.

120 ++-- package.json

121 +`-- packages

122 + `-- a

123 + `-- package.json

124 +```

125 +

126 +The workspaces init also supports the `npm init <initializer> -w <dir>`

127 +syntax, following the same set of rules explained earlier in the initial

128 +**Description** section of this page. Similar to the previous example of

129 +creating a new React-based project using

130 +[`create-react-app`](https://npm.im/create-react-app), the following syntax

131 +will make sure to create the new react app as a nested **workspace** within your

132 +project and configure your `package.json` to recognize it as such:

133 +

134 +```bash

135 +npm init -w packages/my-react-app react-app .

136 +```

137 +

138 +This will make sure to generate your react app as expected, one important

139 +consideration to have in mind is that `npm exec` is going to be run in the

140 +context of the newly created folder for that workspace, and that's the reason

141 +why in this example the initializer uses the initializer name followed with a

142 +dot to represent the current directory in that context, e.g: `react-app .`:

143 +

144 +```

145 +.

146 ++-- package.json

147 +`-- packages

148 + +-- a

149 + | `-- package.json

150 + `-- my-react-app

151 + +-- README

152 + +-- package.json

153 + `-- ...

154 +```

155 +

156 +### Configuration

157 +

158 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

159 +<!-- automatically generated, do not edit manually -->

160 +<!-- see lib/utils/config/definitions.js -->

161 +#### `yes`

162 +

163 +* Default: null

164 +* Type: null or Boolean

165 +

166 +Automatically answer "yes" to any prompts that npm might print on the

167 +command line.

168 +

169 +<!-- automatically generated, do not edit manually -->

170 +<!-- see lib/utils/config/definitions.js -->

171 +

172 +#### `force`

173 +

174 +* Default: false

175 +* Type: Boolean

176 +

177 +Removes various protections against unfortunate side effects, common

178 +mistakes, unnecessary performance degradation, and malicious input.

179 +

180 +* Allow clobbering non-npm files in global installs.

181 +* Allow the `npm version` command to work on an unclean git repository.

182 +* Allow deleting the cache folder with `npm cache clean`.

183 +* Allow installing packages that have an `engines` declaration requiring a

184 + different version of npm.

185 +* Allow installing packages that have an `engines` declaration requiring a

186 + different version of `node`, even if `--engine-strict` is enabled.

187 +* Allow `npm audit fix` to install modules outside your stated dependency

188 + range (including SemVer-major changes).

189 +* Allow unpublishing all versions of a published package.

190 +* Allow conflicting peerDependencies to be installed in the root project.

191 +* Implicitly set `--yes` during `npm init`.

192 +* Allow clobbering existing values in `npm pkg`

193 +

194 +If you don't have a clear idea of what you want to do, it is strongly

195 +recommended that you do not use this option!

196 +

197 +<!-- automatically generated, do not edit manually -->

198 +<!-- see lib/utils/config/definitions.js -->

199 +

200 +#### `workspace`

201 +

202 +* Default:

203 +* Type: String (can be set multiple times)

204 +

205 +Enable running a command in the context of the configured workspaces of the

206 +current project while filtering by running only the workspaces defined by

207 +this configuration option.

208 +

209 +Valid values for the `workspace` config are either:

210 +

211 +* Workspace names

212 +* Path to a workspace directory

213 +* Path to a parent workspace directory (will result in selecting all

214 + workspaces within that folder)

215 +

216 +When set for the `npm init` command, this may be set to the folder of a

217 +workspace which does not yet exist, to create the folder and set it up as a

218 +brand new workspace within the project.

219 +

220 +This value is not exported to the environment for child processes.

221 +

222 +<!-- automatically generated, do not edit manually -->

223 +<!-- see lib/utils/config/definitions.js -->

224 +

225 +#### `workspaces`

226 +

227 +* Default: null

228 +* Type: null or Boolean

229 +

230 +Set to true to run the command in the context of **all** configured

231 +workspaces.

232 +

233 +Explicitly setting this to false will cause commands like `install` to

234 +ignore workspaces altogether. When not set explicitly:

235 +

236 +- Commands that operate on the `node_modules` tree (install, update, etc.)

237 +will link workspaces into the `node_modules` folder. - Commands that do

238 +other things (test, exec, publish, etc.) will operate on the root project,

239 +_unless_ one or more workspaces are specified in the `workspace` config.

240 +

241 +This value is not exported to the environment for child processes.

242 +

243 +<!-- automatically generated, do not edit manually -->

244 +<!-- see lib/utils/config/definitions.js -->

245 +

246 +#### `include-workspace-root`

247 +

248 +* Default: false

249 +* Type: Boolean

250 +

251 +Include the workspace root when workspaces are enabled for a command.

252 +

253 +When false, specifying individual workspaces via the `workspace` config, or

254 +all workspaces via the `workspaces` flag, will cause npm to operate only on

255 +the specified workspaces, and not on the root project.

256 +

257 +<!-- automatically generated, do not edit manually -->

258 +<!-- see lib/utils/config/definitions.js -->

259 +

260 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

261 +

262 +### See Also

263 +

264 +* [init-package-json module](http://npm.im/init-package-json)

265 +* [package.json](/cli/v8/configuring-npm/package-json)

266 +* [npm version](/cli/v8/commands/npm-version)

267 +* [npm scope](/cli/v8/using-npm/scope)

268 +* [npm exec](/cli/v8/commands/npm-exec)

269 +* [npm workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-install-ci-test.md new

+79

@@ -0,0 +1,79 @@

1 +---

2 +title: npm-install-ci-test

3 +section: 1

4 +description: Install a project with a clean slate and run tests

5 +redirect_from:

6 + - /cli/install-ci-test

7 + - /cli/install-ci-test.html

8 + - /cli/commands/install-ci-test

9 + - /cli-commands/install-ci-test

10 + - /cli-commands/install-ci-test.html

11 + - /cli-commands/npm-install-ci-test

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-install-ci-test.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm install-ci-test

21 +

22 +alias: npm cit

23 +```

24 +

25 +### Description

26 +

27 +This command runs `npm ci` followed immediately by `npm test`.

28 +

29 +### Configuration

30 +

31 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

32 +<!-- automatically generated, do not edit manually -->

33 +<!-- see lib/utils/config/definitions.js -->

34 +#### `audit`

35 +

36 +* Default: true

37 +* Type: Boolean

38 +

39 +When "true" submit audit reports alongside the current npm command to the

40 +default registry and all registries configured for scopes. See the

41 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

42 +submitted.

43 +

44 +<!-- automatically generated, do not edit manually -->

45 +<!-- see lib/utils/config/definitions.js -->

46 +

47 +#### `ignore-scripts`

48 +

49 +* Default: false

50 +* Type: Boolean

51 +

52 +If true, npm does not run scripts specified in package.json files.

53 +

54 +Note that commands explicitly intended to run a particular script, such as

55 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

56 +will still run their intended script if `ignore-scripts` is set, but they

57 +will *not* run any pre- or post-scripts.

58 +

59 +<!-- automatically generated, do not edit manually -->

60 +<!-- see lib/utils/config/definitions.js -->

61 +

62 +#### `script-shell`

63 +

64 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

65 +* Type: null or String

66 +

67 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

68 +init <pkg>` commands.

69 +

70 +<!-- automatically generated, do not edit manually -->

71 +<!-- see lib/utils/config/definitions.js -->

72 +

73 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

74 +

75 +### See Also

76 +

77 +* [npm install-test](/cli/v8/commands/npm-install-test)

78 +* [npm ci](/cli/v8/commands/npm-ci)

79 +* [npm test](/cli/v8/commands/npm-test)

content/cli/v8/commands/npm-install-test.md new

+307

@@ -0,0 +1,307 @@

1 +---

2 +title: npm-install-test

3 +section: 1

4 +description: Install package(s) and run tests

5 +redirect_from:

6 + - /cli/install-test

7 + - /cli/install-test.html

8 + - /cli/commands/install-test

9 + - /cli-commands/install-test

10 + - /cli-commands/install-test.html

11 + - /cli-commands/npm-install-test

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-install-test.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm install-test (with no args, in package dir)

21 +npm install-test [<@scope>/]<name>

22 +npm install-test [<@scope>/]<name>@<tag>

23 +npm install-test [<@scope>/]<name>@<version>

24 +npm install-test [<@scope>/]<name>@<version range>

25 +npm install-test <tarball file>

26 +npm install-test <tarball url>

27 +npm install-test <folder>

28 +

29 +alias: npm it

30 +common options: [--save|--save-dev|--save-optional] [--save-exact] [--dry-run]

31 +```

32 +

33 +### Description

34 +

35 +This command runs an `npm install` followed immediately by an `npm test`. It

36 +takes exactly the same arguments as `npm install`.

37 +

38 +### Configuration

39 +

40 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

41 +<!-- automatically generated, do not edit manually -->

42 +<!-- see lib/utils/config/definitions.js -->

43 +#### `save`

44 +

45 +* Default: true

46 +* Type: Boolean

47 +

48 +Save installed packages to a package.json file as dependencies.

49 +

50 +When used with the `npm rm` command, removes the dependency from

51 +package.json.

52 +

53 +<!-- automatically generated, do not edit manually -->

54 +<!-- see lib/utils/config/definitions.js -->

55 +

56 +#### `save-exact`

57 +

58 +* Default: false

59 +* Type: Boolean

60 +

61 +Dependencies saved to package.json will be configured with an exact version

62 +rather than using npm's default semver range operator.

63 +

64 +<!-- automatically generated, do not edit manually -->

65 +<!-- see lib/utils/config/definitions.js -->

66 +

67 +#### `global`

68 +

69 +* Default: false

70 +* Type: Boolean

71 +

72 +Operates in "global" mode, so that packages are installed into the `prefix`

73 +folder instead of the current working directory. See

74 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

75 +

76 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

77 + of the current working directory.

78 +* bin files are linked to `{prefix}/bin`

79 +* man pages are linked to `{prefix}/share/man`

80 +

81 +<!-- automatically generated, do not edit manually -->

82 +<!-- see lib/utils/config/definitions.js -->

83 +

84 +#### `global-style`

85 +

86 +* Default: false

87 +* Type: Boolean

88 +

89 +Causes npm to install the package into your local `node_modules` folder with

90 +the same layout it uses with the global `node_modules` folder. Only your

91 +direct dependencies will show in `node_modules` and everything they depend

92 +on will be flattened in their `node_modules` folders. This obviously will

93 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

94 +will be preferred.

95 +

96 +<!-- automatically generated, do not edit manually -->

97 +<!-- see lib/utils/config/definitions.js -->

98 +

99 +#### `legacy-bundling`

100 +

101 +* Default: false

102 +* Type: Boolean

103 +

104 +Causes npm to install the package such that versions of npm prior to 1.4,

105 +such as the one included with node 0.8, can install the package. This

106 +eliminates all automatic deduping. If used with `global-style` this option

107 +will be preferred.

108 +

109 +<!-- automatically generated, do not edit manually -->

110 +<!-- see lib/utils/config/definitions.js -->

111 +

112 +#### `strict-peer-deps`

113 +

114 +* Default: false

115 +* Type: Boolean

116 +

117 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

118 +conflicting `peerDependencies` will be treated as an install failure, even

119 +if npm could reasonably guess the appropriate resolution based on non-peer

120 +dependency relationships.

121 +

122 +By default, conflicting `peerDependencies` deep in the dependency graph will

123 +be resolved using the nearest non-peer dependency specification, even if

124 +doing so will result in some packages receiving a peer dependency outside

125 +the range set in their package's `peerDependencies` object.

126 +

127 +When such and override is performed, a warning is printed, explaining the

128 +conflict and the packages involved. If `--strict-peer-deps` is set, then

129 +this warning is treated as a failure.

130 +

131 +<!-- automatically generated, do not edit manually -->

132 +<!-- see lib/utils/config/definitions.js -->

133 +

134 +#### `package-lock`

135 +

136 +* Default: true

137 +* Type: Boolean

138 +

139 +If set to false, then ignore `package-lock.json` files when installing. This

140 +will also prevent _writing_ `package-lock.json` if `save` is true.

141 +

142 +When package package-locks are disabled, automatic pruning of extraneous

143 +modules will also be disabled. To remove extraneous modules with

144 +package-locks disabled use `npm prune`.

145 +

146 +<!-- automatically generated, do not edit manually -->

147 +<!-- see lib/utils/config/definitions.js -->

148 +

149 +#### `omit`

150 +

151 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

152 + 'production', otherwise empty.

153 +* Type: "dev", "optional", or "peer" (can be set multiple times)

154 +

155 +Dependency types to omit from the installation tree on disk.

156 +

157 +Note that these dependencies _are_ still resolved and added to the

158 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

159 +physically installed on disk.

160 +

161 +If a package type appears in both the `--include` and `--omit` lists, then

162 +it will be included.

163 +

164 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

165 +variable will be set to `'production'` for all lifecycle scripts.

166 +

167 +<!-- automatically generated, do not edit manually -->

168 +<!-- see lib/utils/config/definitions.js -->

169 +

170 +#### `ignore-scripts`

171 +

172 +* Default: false

173 +* Type: Boolean

174 +

175 +If true, npm does not run scripts specified in package.json files.

176 +

177 +Note that commands explicitly intended to run a particular script, such as

178 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

179 +will still run their intended script if `ignore-scripts` is set, but they

180 +will *not* run any pre- or post-scripts.

181 +

182 +<!-- automatically generated, do not edit manually -->

183 +<!-- see lib/utils/config/definitions.js -->

184 +

185 +#### `audit`

186 +

187 +* Default: true

188 +* Type: Boolean

189 +

190 +When "true" submit audit reports alongside the current npm command to the

191 +default registry and all registries configured for scopes. See the

192 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

193 +submitted.

194 +

195 +<!-- automatically generated, do not edit manually -->

196 +<!-- see lib/utils/config/definitions.js -->

197 +

198 +#### `bin-links`

199 +

200 +* Default: true

201 +* Type: Boolean

202 +

203 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

204 +executables.

205 +

206 +Set to false to have it not do this. This can be used to work around the

207 +fact that some file systems don't support symlinks, even on ostensibly Unix

208 +systems.

209 +

210 +<!-- automatically generated, do not edit manually -->

211 +<!-- see lib/utils/config/definitions.js -->

212 +

213 +#### `fund`

214 +

215 +* Default: true

216 +* Type: Boolean

217 +

218 +When "true" displays the message at the end of each `npm install`

219 +acknowledging the number of dependencies looking for funding. See [`npm

220 +fund`](/cli/v8/commands/npm-fund) for details.

221 +

222 +<!-- automatically generated, do not edit manually -->

223 +<!-- see lib/utils/config/definitions.js -->

224 +

225 +#### `dry-run`

226 +

227 +* Default: false

228 +* Type: Boolean

229 +

230 +Indicates that you don't want npm to make any changes and that it should

231 +only report what it would have done. This can be passed into any of the

232 +commands that modify your local installation, eg, `install`, `update`,

233 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

234 +

235 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

236 +`owner`, etc.

237 +

238 +<!-- automatically generated, do not edit manually -->

239 +<!-- see lib/utils/config/definitions.js -->

240 +

241 +#### `workspace`

242 +

243 +* Default:

244 +* Type: String (can be set multiple times)

245 +

246 +Enable running a command in the context of the configured workspaces of the

247 +current project while filtering by running only the workspaces defined by

248 +this configuration option.

249 +

250 +Valid values for the `workspace` config are either:

251 +

252 +* Workspace names

253 +* Path to a workspace directory

254 +* Path to a parent workspace directory (will result in selecting all

255 + workspaces within that folder)

256 +

257 +When set for the `npm init` command, this may be set to the folder of a

258 +workspace which does not yet exist, to create the folder and set it up as a

259 +brand new workspace within the project.

260 +

261 +This value is not exported to the environment for child processes.

262 +

263 +<!-- automatically generated, do not edit manually -->

264 +<!-- see lib/utils/config/definitions.js -->

265 +

266 +#### `workspaces`

267 +

268 +* Default: null

269 +* Type: null or Boolean

270 +

271 +Set to true to run the command in the context of **all** configured

272 +workspaces.

273 +

274 +Explicitly setting this to false will cause commands like `install` to

275 +ignore workspaces altogether. When not set explicitly:

276 +

277 +- Commands that operate on the `node_modules` tree (install, update, etc.)

278 +will link workspaces into the `node_modules` folder. - Commands that do

279 +other things (test, exec, publish, etc.) will operate on the root project,

280 +_unless_ one or more workspaces are specified in the `workspace` config.

281 +

282 +This value is not exported to the environment for child processes.

283 +

284 +<!-- automatically generated, do not edit manually -->

285 +<!-- see lib/utils/config/definitions.js -->

286 +

287 +#### `include-workspace-root`

288 +

289 +* Default: false

290 +* Type: Boolean

291 +

292 +Include the workspace root when workspaces are enabled for a command.

293 +

294 +When false, specifying individual workspaces via the `workspace` config, or

295 +all workspaces via the `workspaces` flag, will cause npm to operate only on

296 +the specified workspaces, and not on the root project.

297 +

298 +<!-- automatically generated, do not edit manually -->

299 +<!-- see lib/utils/config/definitions.js -->

300 +

301 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

302 +

303 +### See Also

304 +

305 +* [npm install](/cli/v8/commands/npm-install)

306 +* [npm install-ci-test](/cli/v8/commands/npm-install-ci-test)

307 +* [npm test](/cli/v8/commands/npm-test)

content/cli/v8/commands/npm-install.md new

+738

@@ -0,0 +1,738 @@

1 +---

2 +title: npm-install

3 +section: 1

4 +description: Install a package

5 +redirect_from:

6 + - /cli/install

7 + - /cli/install.html

8 + - /cli/commands/install

9 + - /cli-commands/install

10 + - /cli-commands/install.html

11 + - /cli-commands/npm-install

12 + - /cli-documentation/install

13 +github_repo: npm/cli

14 +github_branch: latest

15 +github_path: docs/content/commands/npm-install.md

16 +---

17 +

18 +### Synopsis

19 +

20 +```bash

21 +npm install (with no args, in package dir)

22 +npm install [<@scope>/]<name>

23 +npm install [<@scope>/]<name>@<tag>

24 +npm install [<@scope>/]<name>@<version>

25 +npm install [<@scope>/]<name>@<version range>

26 +npm install <alias>@npm:<name>

27 +npm install <git-host>:<git-user>/<repo-name>

28 +npm install <git repo url>

29 +npm install <tarball file>

30 +npm install <tarball url>

31 +npm install <folder>

32 +

33 +aliases: npm i, npm add

34 +common options: [-P|--save-prod|-D|--save-dev|-O|--save-optional|--save-peer] [-E|--save-exact] [-B|--save-bundle] [--no-save] [--dry-run]

35 +```

36 +

37 +### Description

38 +

39 +This command installs a package and any packages that it depends on. If the

40 +package has a package-lock, or an npm shrinkwrap file, or a yarn lock file,

41 +the installation of dependencies will be driven by that, respecting the

42 +following order of precedence:

43 +

44 +* `npm-shrinkwrap.json`

45 +* `package-lock.json`

46 +* `yarn.lock`

47 +

48 +See [package-lock.json](/cli/v8/configuring-npm/package-lock-json) and

49 +[`npm shrinkwrap`](/cli/v8/commands/npm-shrinkwrap).

50 +

51 +A `package` is:

52 +

53 +* a) a folder containing a program described by a

54 + [`package.json`](/cli/v8/configuring-npm/package-json) file

55 +* b) a gzipped tarball containing (a)

56 +* c) a url that resolves to (b)

57 +* d) a `<name>@<version>` that is published on the registry (see

58 + [`registry`](/cli/v8/using-npm/registry)) with (c)

59 +* e) a `<name>@<tag>` (see [`npm dist-tag`](/cli/v8/commands/npm-dist-tag)) that

60 + points to (d)

61 +* f) a `<name>` that has a "latest" tag satisfying (e)

62 +* g) a `<git remote url>` that resolves to (a)

63 +

64 +Even if you never publish your package, you can still get a lot of benefits

65 +of using npm if you just want to write a node program (a), and perhaps if

66 +you also want to be able to easily install it elsewhere after packing it up

67 +into a tarball (b).

68 +

69 +

70 +* `npm install` (in a package directory, no arguments):

71 +

72 + Install the dependencies in the local `node_modules` folder.

73 +

74 + In global mode (ie, with `-g` or `--global` appended to the command),

75 + it installs the current package context (ie, the current working

76 + directory) as a global package.

77 +

78 + By default, `npm install` will install all modules listed as

79 + dependencies in [`package.json`](/cli/v8/configuring-npm/package-json).

80 +

81 + With the `--production` flag (or when the `NODE_ENV` environment

82 + variable is set to `production`), npm will not install modules listed

83 + in `devDependencies`. To install all modules listed in both

84 + `dependencies` and `devDependencies` when `NODE_ENV` environment

85 + variable is set to `production`, you can use `--production=false`.

86 +

87 + > NOTE: The `--production` flag has no particular meaning when adding a

88 + dependency to a project.

89 +

90 +* `npm install <folder>`:

91 +

92 + Install the package in the directory as a symlink in the current

93 + project. Its dependencies will be installed before it's linked. If

94 + `<folder>` sits inside the root of your project, its dependencies may

95 + be hoisted to the top-level `node_modules` as they would for other

96 + types of dependencies.

97 +

98 +* `npm install <tarball file>`:

99 +

100 + Install a package that is sitting on the filesystem. Note: if you just

101 + want to link a dev directory into your npm root, you can do this more

102 + easily by using [`npm link`](/cli/v8/commands/npm-link).

103 +

104 + Tarball requirements:

105 + * The filename *must* use `.tar`, `.tar.gz`, or `.tgz` as the

106 + extension.

107 + * The package contents should reside in a subfolder inside the tarball

108 + (usually it is called `package/`). npm strips one directory layer

109 + when installing the package (an equivalent of `tar x

110 + --strip-components=1` is run).

111 + * The package must contain a `package.json` file with `name` and

112 + `version` properties.

113 +

114 + Example:

115 +

116 + ```bash

117 + npm install ./package.tgz

118 + ```

119 +

120 +* `npm install <tarball url>`:

121 +

122 + Fetch the tarball url, and then install it. In order to distinguish between

123 + this and other options, the argument must start with "http://" or "https://"

124 +

125 + Example:

126 +

127 + ```bash

128 + npm install https://github.com/indexzero/forever/tarball/v0.5.6

129 + ```

130 +

131 +* `npm install [<@scope>/]<name>`:

132 +

133 + Do a `<name>@<tag>` install, where `<tag>` is the "tag" config. (See

134 + [`config`](/cli/v8/using-npm/config). The config's default value is `latest`.)

135 +

136 + In most cases, this will install the version of the modules tagged as

137 + `latest` on the npm registry.

138 +

139 + Example:

140 +

141 + ```bash

142 + npm install sax

143 + ```

144 +

145 + `npm install` saves any specified packages into `dependencies` by default.

146 + Additionally, you can control where and how they get saved with some

147 + additional flags:

148 +

149 + * `-P, --save-prod`: Package will appear in your `dependencies`. This

150 + is the default unless `-D` or `-O` are present.

151 +

152 + * `-D, --save-dev`: Package will appear in your `devDependencies`.

153 +

154 + * `-O, --save-optional`: Package will appear in your

155 + `optionalDependencies`.

156 +

157 + * `--no-save`: Prevents saving to `dependencies`.

158 +

159 + When using any of the above options to save dependencies to your

160 + package.json, there are two additional, optional flags:

161 +

162 + * `-E, --save-exact`: Saved dependencies will be configured with an

163 + exact version rather than using npm's default semver range operator.

164 +

165 + * `-B, --save-bundle`: Saved dependencies will also be added to your

166 + `bundleDependencies` list.

167 +

168 + Further, if you have an `npm-shrinkwrap.json` or `package-lock.json`

169 + then it will be updated as well.

170 +

171 + `<scope>` is optional. The package will be downloaded from the registry

172 + associated with the specified scope. If no registry is associated with

173 + the given scope the default registry is assumed. See

174 + [`scope`](/cli/v8/using-npm/scope).

175 +

176 + Note: if you do not include the @-symbol on your scope name, npm will

177 + interpret this as a GitHub repository instead, see below. Scopes names

178 + must also be followed by a slash.

179 +

180 + Examples:

181 +

182 + ```bash

183 + npm install sax

184 + npm install githubname/reponame

185 + npm install @myorg/privatepackage

186 + npm install node-tap --save-dev

187 + npm install dtrace-provider --save-optional

188 + npm install readable-stream --save-exact

189 + npm install ansi-regex --save-bundle

190 + ```

191 +

192 + **Note**: If there is a file or folder named `<name>` in the current

193 + working directory, then it will try to install that, and only try to

194 + fetch the package by name if it is not valid.

195 +

196 +* `npm install <alias>@npm:<name>`:

197 +

198 + Install a package under a custom alias. Allows multiple versions of

199 + a same-name package side-by-side, more convenient import names for

200 + packages with otherwise long ones, and using git forks replacements

201 + or forked npm packages as replacements. Aliasing works only on your

202 + project and does not rename packages in transitive dependencies.

203 + Aliases should follow the naming conventions stated in

204 + [`validate-npm-package-name`](https://www.npmjs.com/package/validate-npm-package-name#naming-rules).

205 +

206 + Examples:

207 +

208 + ```bash

209 + npm install my-react@npm:react

210 + npm install jquery2@npm:jquery@2

211 + npm install jquery3@npm:jquery@3

212 + npm install npa@npm:npm-package-arg

213 + ```

214 +

215 +* `npm install [<@scope>/]<name>@<tag>`:

216 +

217 + Install the version of the package that is referenced by the specified tag.

218 + If the tag does not exist in the registry data for that package, then this

219 + will fail.

220 +

221 + Example:

222 +

223 + ```bash

224 + npm install sax@latest

225 + npm install @myorg/mypackage@latest

226 + ```

227 +

228 +* `npm install [<@scope>/]<name>@<version>`:

229 +

230 + Install the specified version of the package. This will fail if the

231 + version has not been published to the registry.

232 +

233 + Example:

234 +

235 + ```bash

236 + npm install sax@0.1.1

237 + npm install @myorg/privatepackage@1.5.0

238 + ```

239 +

240 +* `npm install [<@scope>/]<name>@<version range>`:

241 +

242 + Install a version of the package matching the specified version range.

243 + This will follow the same rules for resolving dependencies described in

244 + [`package.json`](/cli/v8/configuring-npm/package-json).

245 +

246 + Note that most version ranges must be put in quotes so that your shell

247 + will treat it as a single argument.

248 +

249 + Example:

250 +

251 + ```bash

252 + npm install sax@">=0.1.0 <0.2.0"

253 + npm install @myorg/privatepackage@"16 - 17"

254 + ```

255 +

256 +* `npm install <git remote url>`:

257 +

258 + Installs the package from the hosted git provider, cloning it with

259 + `git`. For a full git remote url, only that URL will be attempted.

260 +

261 + ```bash

262 + <protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

263 + ```

264 +

265 + `<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or

266 + `git+file`.

267 +

268 + If `#<commit-ish>` is provided, it will be used to clone exactly that

269 + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>`

270 + can be any valid semver range or exact version, and npm will look for

271 + any tags or refs matching that range in the remote repository, much as

272 + it would for a registry dependency. If neither `#<commit-ish>` or

273 + `#semver:<semver>` is specified, then the default branch of the

274 + repository is used.

275 +

276 + If the repository makes use of submodules, those submodules will be

277 + cloned as well.

278 +

279 + If the package being installed contains a `prepare` script, its

280 + `dependencies` and `devDependencies` will be installed, and the prepare

281 + script will be run, before the package is packaged and installed.

282 +

283 + The following git environment variables are recognized by npm and will

284 + be added to the environment when running git:

285 +

286 + * `GIT_ASKPASS`

287 + * `GIT_EXEC_PATH`

288 + * `GIT_PROXY_COMMAND`

289 + * `GIT_SSH`

290 + * `GIT_SSH_COMMAND`

291 + * `GIT_SSL_CAINFO`

292 + * `GIT_SSL_NO_VERIFY`

293 +

294 + See the git man page for details.

295 +

296 + Examples:

297 +

298 + ```bash

299 + npm install git+ssh://git@github.com:npm/cli.git#v1.0.27

300 + npm install git+ssh://git@github.com:npm/cli#pull/273

301 + npm install git+ssh://git@github.com:npm/cli#semver:^5.0

302 + npm install git+https://isaacs@github.com/npm/cli.git

303 + npm install git://github.com/npm/cli.git#v1.0.27

304 + GIT_SSH_COMMAND='ssh -i ~/.ssh/custom_ident' npm install git+ssh://git@github.com:npm/cli.git

305 + ```

306 +

307 +* `npm install <githubname>/<githubrepo>[#<commit-ish>]`:

308 +* `npm install github:<githubname>/<githubrepo>[#<commit-ish>]`:

309 +

310 + Install the package at `https://github.com/githubname/githubrepo` by

311 + attempting to clone it using `git`.

312 +

313 + If `#<commit-ish>` is provided, it will be used to clone exactly that

314 + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>`

315 + can be any valid semver range or exact version, and npm will look for

316 + any tags or refs matching that range in the remote repository, much as

317 + it would for a registry dependency. If neither `#<commit-ish>` or

318 + `#semver:<semver>` is specified, then `master` is used.

319 +

320 + As with regular git dependencies, `dependencies` and `devDependencies`

321 + will be installed if the package has a `prepare` script before the

322 + package is done installing.

323 +

324 + Examples:

325 +

326 + ```bash

327 + npm install mygithubuser/myproject

328 + npm install github:mygithubuser/myproject

329 + ```

330 +

331 +* `npm install gist:[<githubname>/]<gistID>[#<commit-ish>|#semver:<semver>]`:

332 +

333 + Install the package at `https://gist.github.com/gistID` by attempting to

334 + clone it using `git`. The GitHub username associated with the gist is

335 + optional and will not be saved in `package.json`.

336 +

337 + As with regular git dependencies, `dependencies` and `devDependencies` will

338 + be installed if the package has a `prepare` script before the package is

339 + done installing.

340 +

341 + Example:

342 +

343 + ```bash

344 + npm install gist:101a11beef

345 + ```

346 +

347 +* `npm install bitbucket:<bitbucketname>/<bitbucketrepo>[#<commit-ish>]`:

348 +

349 + Install the package at `https://bitbucket.org/bitbucketname/bitbucketrepo`

350 + by attempting to clone it using `git`.

351 +

352 + If `#<commit-ish>` is provided, it will be used to clone exactly that

353 + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can

354 + be any valid semver range or exact version, and npm will look for any tags

355 + or refs matching that range in the remote repository, much as it would for a

356 + registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is

357 + specified, then `master` is used.

358 +

359 + As with regular git dependencies, `dependencies` and `devDependencies` will

360 + be installed if the package has a `prepare` script before the package is

361 + done installing.

362 +

363 + Example:

364 +

365 + ```bash

366 + npm install bitbucket:mybitbucketuser/myproject

367 + ```

368 +

369 +* `npm install gitlab:<gitlabname>/<gitlabrepo>[#<commit-ish>]`:

370 +

371 + Install the package at `https://gitlab.com/gitlabname/gitlabrepo`

372 + by attempting to clone it using `git`.

373 +

374 + If `#<commit-ish>` is provided, it will be used to clone exactly that

375 + commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can

376 + be any valid semver range or exact version, and npm will look for any tags

377 + or refs matching that range in the remote repository, much as it would for a

378 + registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is

379 + specified, then `master` is used.

380 +

381 + As with regular git dependencies, `dependencies` and `devDependencies` will

382 + be installed if the package has a `prepare` script before the package is

383 + done installing.

384 +

385 + Example:

386 +

387 + ```bash

388 + npm install gitlab:mygitlabuser/myproject

389 + npm install gitlab:myusr/myproj#semver:^5.0

390 + ```

391 +

392 +You may combine multiple arguments and even multiple types of arguments.

393 +For example:

394 +

395 +```bash

396 +npm install sax@">=0.1.0 <0.2.0" bench supervisor

397 +```

398 +

399 +The `--tag` argument will apply to all of the specified install targets. If

400 +a tag with the given name exists, the tagged version is preferred over

401 +newer versions.

402 +

403 +The `--dry-run` argument will report in the usual way what the install

404 +would have done without actually installing anything.

405 +

406 +The `--package-lock-only` argument will only update the

407 +`package-lock.json`, instead of checking `node_modules` and downloading

408 +dependencies.

409 +

410 +The `-f` or `--force` argument will force npm to fetch remote resources

411 +even if a local copy exists on disk.

412 +

413 +```bash

414 +npm install sax --force

415 +```

416 +

417 +### Configuration

418 +

419 +See the [`config`](/cli/v8/using-npm/config) help doc. Many of the configuration

420 +params have some effect on installation, since that's most of what npm

421 +does.

422 +

423 +These are some of the most common options related to installation.

424 +

425 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

426 +<!-- automatically generated, do not edit manually -->

427 +<!-- see lib/utils/config/definitions.js -->

428 +#### `save`

429 +

430 +* Default: true

431 +* Type: Boolean

432 +

433 +Save installed packages to a package.json file as dependencies.

434 +

435 +When used with the `npm rm` command, removes the dependency from

436 +package.json.

437 +

438 +<!-- automatically generated, do not edit manually -->

439 +<!-- see lib/utils/config/definitions.js -->

440 +

441 +#### `save-exact`

442 +

443 +* Default: false

444 +* Type: Boolean

445 +

446 +Dependencies saved to package.json will be configured with an exact version

447 +rather than using npm's default semver range operator.

448 +

449 +<!-- automatically generated, do not edit manually -->

450 +<!-- see lib/utils/config/definitions.js -->

451 +

452 +#### `global`

453 +

454 +* Default: false

455 +* Type: Boolean

456 +

457 +Operates in "global" mode, so that packages are installed into the `prefix`

458 +folder instead of the current working directory. See

459 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

460 +

461 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

462 + of the current working directory.

463 +* bin files are linked to `{prefix}/bin`

464 +* man pages are linked to `{prefix}/share/man`

465 +

466 +<!-- automatically generated, do not edit manually -->

467 +<!-- see lib/utils/config/definitions.js -->

468 +

469 +#### `global-style`

470 +

471 +* Default: false

472 +* Type: Boolean

473 +

474 +Causes npm to install the package into your local `node_modules` folder with

475 +the same layout it uses with the global `node_modules` folder. Only your

476 +direct dependencies will show in `node_modules` and everything they depend

477 +on will be flattened in their `node_modules` folders. This obviously will

478 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

479 +will be preferred.

480 +

481 +<!-- automatically generated, do not edit manually -->

482 +<!-- see lib/utils/config/definitions.js -->

483 +

484 +#### `legacy-bundling`

485 +

486 +* Default: false

487 +* Type: Boolean

488 +

489 +Causes npm to install the package such that versions of npm prior to 1.4,

490 +such as the one included with node 0.8, can install the package. This

491 +eliminates all automatic deduping. If used with `global-style` this option

492 +will be preferred.

493 +

494 +<!-- automatically generated, do not edit manually -->

495 +<!-- see lib/utils/config/definitions.js -->

496 +

497 +#### `strict-peer-deps`

498 +

499 +* Default: false

500 +* Type: Boolean

501 +

502 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

503 +conflicting `peerDependencies` will be treated as an install failure, even

504 +if npm could reasonably guess the appropriate resolution based on non-peer

505 +dependency relationships.

506 +

507 +By default, conflicting `peerDependencies` deep in the dependency graph will

508 +be resolved using the nearest non-peer dependency specification, even if

509 +doing so will result in some packages receiving a peer dependency outside

510 +the range set in their package's `peerDependencies` object.

511 +

512 +When such and override is performed, a warning is printed, explaining the

513 +conflict and the packages involved. If `--strict-peer-deps` is set, then

514 +this warning is treated as a failure.

515 +

516 +<!-- automatically generated, do not edit manually -->

517 +<!-- see lib/utils/config/definitions.js -->

518 +

519 +#### `package-lock`

520 +

521 +* Default: true

522 +* Type: Boolean

523 +

524 +If set to false, then ignore `package-lock.json` files when installing. This

525 +will also prevent _writing_ `package-lock.json` if `save` is true.

526 +

527 +When package package-locks are disabled, automatic pruning of extraneous

528 +modules will also be disabled. To remove extraneous modules with

529 +package-locks disabled use `npm prune`.

530 +

531 +<!-- automatically generated, do not edit manually -->

532 +<!-- see lib/utils/config/definitions.js -->

533 +

534 +#### `omit`

535 +

536 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

537 + 'production', otherwise empty.

538 +* Type: "dev", "optional", or "peer" (can be set multiple times)

539 +

540 +Dependency types to omit from the installation tree on disk.

541 +

542 +Note that these dependencies _are_ still resolved and added to the

543 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

544 +physically installed on disk.

545 +

546 +If a package type appears in both the `--include` and `--omit` lists, then

547 +it will be included.

548 +

549 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

550 +variable will be set to `'production'` for all lifecycle scripts.

551 +

552 +<!-- automatically generated, do not edit manually -->

553 +<!-- see lib/utils/config/definitions.js -->

554 +

555 +#### `ignore-scripts`

556 +

557 +* Default: false

558 +* Type: Boolean

559 +

560 +If true, npm does not run scripts specified in package.json files.

561 +

562 +Note that commands explicitly intended to run a particular script, such as

563 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

564 +will still run their intended script if `ignore-scripts` is set, but they

565 +will *not* run any pre- or post-scripts.

566 +

567 +<!-- automatically generated, do not edit manually -->

568 +<!-- see lib/utils/config/definitions.js -->

569 +

570 +#### `audit`

571 +

572 +* Default: true

573 +* Type: Boolean

574 +

575 +When "true" submit audit reports alongside the current npm command to the

576 +default registry and all registries configured for scopes. See the

577 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

578 +submitted.

579 +

580 +<!-- automatically generated, do not edit manually -->

581 +<!-- see lib/utils/config/definitions.js -->

582 +

583 +#### `bin-links`

584 +

585 +* Default: true

586 +* Type: Boolean

587 +

588 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

589 +executables.

590 +

591 +Set to false to have it not do this. This can be used to work around the

592 +fact that some file systems don't support symlinks, even on ostensibly Unix

593 +systems.

594 +

595 +<!-- automatically generated, do not edit manually -->

596 +<!-- see lib/utils/config/definitions.js -->

597 +

598 +#### `fund`

599 +

600 +* Default: true

601 +* Type: Boolean

602 +

603 +When "true" displays the message at the end of each `npm install`

604 +acknowledging the number of dependencies looking for funding. See [`npm

605 +fund`](/cli/v8/commands/npm-fund) for details.

606 +

607 +<!-- automatically generated, do not edit manually -->

608 +<!-- see lib/utils/config/definitions.js -->

609 +

610 +#### `dry-run`

611 +

612 +* Default: false

613 +* Type: Boolean

614 +

615 +Indicates that you don't want npm to make any changes and that it should

616 +only report what it would have done. This can be passed into any of the

617 +commands that modify your local installation, eg, `install`, `update`,

618 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

619 +

620 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

621 +`owner`, etc.

622 +

623 +<!-- automatically generated, do not edit manually -->

624 +<!-- see lib/utils/config/definitions.js -->

625 +

626 +#### `workspace`

627 +

628 +* Default:

629 +* Type: String (can be set multiple times)

630 +

631 +Enable running a command in the context of the configured workspaces of the

632 +current project while filtering by running only the workspaces defined by

633 +this configuration option.

634 +

635 +Valid values for the `workspace` config are either:

636 +

637 +* Workspace names

638 +* Path to a workspace directory

639 +* Path to a parent workspace directory (will result in selecting all

640 + workspaces within that folder)

641 +

642 +When set for the `npm init` command, this may be set to the folder of a

643 +workspace which does not yet exist, to create the folder and set it up as a

644 +brand new workspace within the project.

645 +

646 +This value is not exported to the environment for child processes.

647 +

648 +<!-- automatically generated, do not edit manually -->

649 +<!-- see lib/utils/config/definitions.js -->

650 +

651 +#### `workspaces`

652 +

653 +* Default: null

654 +* Type: null or Boolean

655 +

656 +Set to true to run the command in the context of **all** configured

657 +workspaces.

658 +

659 +Explicitly setting this to false will cause commands like `install` to

660 +ignore workspaces altogether. When not set explicitly:

661 +

662 +- Commands that operate on the `node_modules` tree (install, update, etc.)

663 +will link workspaces into the `node_modules` folder. - Commands that do

664 +other things (test, exec, publish, etc.) will operate on the root project,

665 +_unless_ one or more workspaces are specified in the `workspace` config.

666 +

667 +This value is not exported to the environment for child processes.

668 +

669 +<!-- automatically generated, do not edit manually -->

670 +<!-- see lib/utils/config/definitions.js -->

671 +

672 +#### `include-workspace-root`

673 +

674 +* Default: false

675 +* Type: Boolean

676 +

677 +Include the workspace root when workspaces are enabled for a command.

678 +

679 +When false, specifying individual workspaces via the `workspace` config, or

680 +all workspaces via the `workspaces` flag, will cause npm to operate only on

681 +the specified workspaces, and not on the root project.

682 +

683 +<!-- automatically generated, do not edit manually -->

684 +<!-- see lib/utils/config/definitions.js -->

685 +

686 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

687 +

688 +### Algorithm

689 +

690 +Given a `package{dep}` structure: `A{B,C}, B{C}, C{D}`,

691 +the npm install algorithm produces:

692 +

693 +```bash

694 +A

695 ++-- B

696 ++-- C

697 ++-- D

698 +```

699 +

700 +That is, the dependency from B to C is satisfied by the fact that A already

701 +caused C to be installed at a higher level. D is still installed at the top

702 +level because nothing conflicts with it.

703 +

704 +For `A{B,C}, B{C,D@1}, C{D@2}`, this algorithm produces:

705 +

706 +```bash

707 +A

708 ++-- B

709 ++-- C

710 + `-- D@2

711 ++-- D@1

712 +```

713 +

714 +Because B's D@1 will be installed in the top-level, C now has to install

715 +D@2 privately for itself. This algorithm is deterministic, but different

716 +trees may be produced if two dependencies are requested for installation in

717 +a different order.

718 +

719 +See [folders](/cli/v8/configuring-npm/folders) for a more detailed description of

720 +the specific folder structures that npm creates.

721 +

722 +### See Also

723 +

724 +* [npm folders](/cli/v8/configuring-npm/folders)

725 +* [npm update](/cli/v8/commands/npm-update)

726 +* [npm audit](/cli/v8/commands/npm-audit)

727 +* [npm fund](/cli/v8/commands/npm-fund)

728 +* [npm link](/cli/v8/commands/npm-link)

729 +* [npm rebuild](/cli/v8/commands/npm-rebuild)

730 +* [npm scripts](/cli/v8/using-npm/scripts)

731 +* [npm config](/cli/v8/commands/npm-config)

732 +* [npmrc](/cli/v8/configuring-npm/npmrc)

733 +* [npm registry](/cli/v8/using-npm/registry)

734 +* [npm dist-tag](/cli/v8/commands/npm-dist-tag)

735 +* [npm uninstall](/cli/v8/commands/npm-uninstall)

736 +* [npm shrinkwrap](/cli/v8/commands/npm-shrinkwrap)

737 +* [package.json](/cli/v8/configuring-npm/package-json)

738 +* [workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-link.md new

+394

@@ -0,0 +1,394 @@

1 +---

2 +title: npm-link

3 +section: 1

4 +description: Symlink a package folder

5 +redirect_from:

6 + - /cli/link

7 + - /cli/link.html

8 + - /cli/commands/link

9 + - /cli-commands/link

10 + - /cli-commands/link.html

11 + - /cli-commands/npm-link

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-link.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm link (in package dir)

21 +npm link [<@scope>/]<pkg>[@<version>]

22 +

23 +alias: npm ln

24 +```

25 +

26 +### Description

27 +

28 +This is handy for installing your own stuff, so that you can work on it and

29 +test iteratively without having to continually rebuild.

30 +

31 +Package linking is a two-step process.

32 +

33 +First, `npm link` in a package folder will create a symlink in the global

34 +folder `{prefix}/lib/node_modules/<package>` that links to the package

35 +where the `npm link` command was executed. It will also link any bins in

36 +the package to `{prefix}/bin/{name}`. Note that `npm link` uses the global

37 +prefix (see `npm prefix -g` for its value).

38 +

39 +Next, in some other location, `npm link package-name` will create a

40 +symbolic link from globally-installed `package-name` to `node_modules/` of

41 +the current folder.

42 +

43 +Note that `package-name` is taken from `package.json`, _not_ from the

44 +directory name.

45 +

46 +The package name can be optionally prefixed with a scope. See

47 +[`scope`](/cli/v8/using-npm/scope). The scope must be preceded by an @-symbol and

48 +followed by a slash.

49 +

50 +When creating tarballs for `npm publish`, the linked packages are

51 +"snapshotted" to their current state by resolving the symbolic links, if

52 +they are included in `bundleDependencies`.

53 +

54 +For example:

55 +

56 +```bash

57 +cd ~/projects/node-redis # go into the package directory

58 +npm link # creates global link

59 +cd ~/projects/node-bloggy # go into some other package directory.

60 +npm link redis # link-install the package

61 +```

62 +

63 +Now, any changes to `~/projects/node-redis` will be reflected in

64 +`~/projects/node-bloggy/node_modules/node-redis/`. Note that the link

65 +should be to the package name, not the directory name for that package.

66 +

67 +You may also shortcut the two steps in one. For example, to do the

68 +above use-case in a shorter way:

69 +

70 +```bash

71 +cd ~/projects/node-bloggy # go into the dir of your main project

72 +npm link ../node-redis # link the dir of your dependency

73 +```

74 +

75 +The second line is the equivalent of doing:

76 +

77 +```bash

78 +(cd ../node-redis; npm link)

79 +npm link redis

80 +```

81 +

82 +That is, it first creates a global link, and then links the global

83 +installation target into your project's `node_modules` folder.

84 +

85 +Note that in this case, you are referring to the directory name,

86 +`node-redis`, rather than the package name `redis`.

87 +

88 +If your linked package is scoped (see [`scope`](/cli/v8/using-npm/scope)) your

89 +link command must include that scope, e.g.

90 +

91 +```bash

92 +npm link @myorg/privatepackage

93 +```

94 +

95 +### Caveat

96 +

97 +Note that package dependencies linked in this way are _not_ saved to

98 +`package.json` by default, on the assumption that the intention is to have

99 +a link stand in for a regular non-link dependency. Otherwise, for example,

100 +if you depend on `redis@^3.0.1`, and ran `npm link redis`, it would replace

101 +the `^3.0.1` dependency with `file:../path/to/node-redis`, which you

102 +probably don't want! Additionally, other users or developers on your

103 +project would run into issues if they do not have their folders set up

104 +exactly the same as yours.

105 +

106 +If you are adding a _new_ dependency as a link, you should add it to the

107 +relevant metadata by running `npm install <dep> --package-lock-only`.

108 +

109 +If you _want_ to save the `file:` reference in your `package.json` and

110 +`package-lock.json` files, you can use `npm link <dep> --save` to do so.

111 +

112 +### Workspace Usage

113 +

114 +`npm link <pkg> --workspace <name>` will link the relevant package as a

115 +dependency of the specified workspace(s). Note that It may actually be

116 +linked into the parent project's `node_modules` folder, if there are no

117 +conflicting dependencies.

118 +

119 +`npm link --workspace <name>` will create a global link to the specified

120 +workspace(s).

121 +

122 +### Configuration

123 +

124 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

125 +<!-- automatically generated, do not edit manually -->

126 +<!-- see lib/utils/config/definitions.js -->

127 +#### `save`

128 +

129 +* Default: true

130 +* Type: Boolean

131 +

132 +Save installed packages to a package.json file as dependencies.

133 +

134 +When used with the `npm rm` command, removes the dependency from

135 +package.json.

136 +

137 +<!-- automatically generated, do not edit manually -->

138 +<!-- see lib/utils/config/definitions.js -->

139 +

140 +#### `save-exact`

141 +

142 +* Default: false

143 +* Type: Boolean

144 +

145 +Dependencies saved to package.json will be configured with an exact version

146 +rather than using npm's default semver range operator.

147 +

148 +<!-- automatically generated, do not edit manually -->

149 +<!-- see lib/utils/config/definitions.js -->

150 +

151 +#### `global`

152 +

153 +* Default: false

154 +* Type: Boolean

155 +

156 +Operates in "global" mode, so that packages are installed into the `prefix`

157 +folder instead of the current working directory. See

158 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

159 +

160 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

161 + of the current working directory.

162 +* bin files are linked to `{prefix}/bin`

163 +* man pages are linked to `{prefix}/share/man`

164 +

165 +<!-- automatically generated, do not edit manually -->

166 +<!-- see lib/utils/config/definitions.js -->

167 +

168 +#### `global-style`

169 +

170 +* Default: false

171 +* Type: Boolean

172 +

173 +Causes npm to install the package into your local `node_modules` folder with

174 +the same layout it uses with the global `node_modules` folder. Only your

175 +direct dependencies will show in `node_modules` and everything they depend

176 +on will be flattened in their `node_modules` folders. This obviously will

177 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

178 +will be preferred.

179 +

180 +<!-- automatically generated, do not edit manually -->

181 +<!-- see lib/utils/config/definitions.js -->

182 +

183 +#### `legacy-bundling`

184 +

185 +* Default: false

186 +* Type: Boolean

187 +

188 +Causes npm to install the package such that versions of npm prior to 1.4,

189 +such as the one included with node 0.8, can install the package. This

190 +eliminates all automatic deduping. If used with `global-style` this option

191 +will be preferred.

192 +

193 +<!-- automatically generated, do not edit manually -->

194 +<!-- see lib/utils/config/definitions.js -->

195 +

196 +#### `strict-peer-deps`

197 +

198 +* Default: false

199 +* Type: Boolean

200 +

201 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

202 +conflicting `peerDependencies` will be treated as an install failure, even

203 +if npm could reasonably guess the appropriate resolution based on non-peer

204 +dependency relationships.

205 +

206 +By default, conflicting `peerDependencies` deep in the dependency graph will

207 +be resolved using the nearest non-peer dependency specification, even if

208 +doing so will result in some packages receiving a peer dependency outside

209 +the range set in their package's `peerDependencies` object.

210 +

211 +When such and override is performed, a warning is printed, explaining the

212 +conflict and the packages involved. If `--strict-peer-deps` is set, then

213 +this warning is treated as a failure.

214 +

215 +<!-- automatically generated, do not edit manually -->

216 +<!-- see lib/utils/config/definitions.js -->

217 +

218 +#### `package-lock`

219 +

220 +* Default: true

221 +* Type: Boolean

222 +

223 +If set to false, then ignore `package-lock.json` files when installing. This

224 +will also prevent _writing_ `package-lock.json` if `save` is true.

225 +

226 +When package package-locks are disabled, automatic pruning of extraneous

227 +modules will also be disabled. To remove extraneous modules with

228 +package-locks disabled use `npm prune`.

229 +

230 +<!-- automatically generated, do not edit manually -->

231 +<!-- see lib/utils/config/definitions.js -->

232 +

233 +#### `omit`

234 +

235 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

236 + 'production', otherwise empty.

237 +* Type: "dev", "optional", or "peer" (can be set multiple times)

238 +

239 +Dependency types to omit from the installation tree on disk.

240 +

241 +Note that these dependencies _are_ still resolved and added to the

242 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

243 +physically installed on disk.

244 +

245 +If a package type appears in both the `--include` and `--omit` lists, then

246 +it will be included.

247 +

248 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

249 +variable will be set to `'production'` for all lifecycle scripts.

250 +

251 +<!-- automatically generated, do not edit manually -->

252 +<!-- see lib/utils/config/definitions.js -->

253 +

254 +#### `ignore-scripts`

255 +

256 +* Default: false

257 +* Type: Boolean

258 +

259 +If true, npm does not run scripts specified in package.json files.

260 +

261 +Note that commands explicitly intended to run a particular script, such as

262 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

263 +will still run their intended script if `ignore-scripts` is set, but they

264 +will *not* run any pre- or post-scripts.

265 +

266 +<!-- automatically generated, do not edit manually -->

267 +<!-- see lib/utils/config/definitions.js -->

268 +

269 +#### `audit`

270 +

271 +* Default: true

272 +* Type: Boolean

273 +

274 +When "true" submit audit reports alongside the current npm command to the

275 +default registry and all registries configured for scopes. See the

276 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

277 +submitted.

278 +

279 +<!-- automatically generated, do not edit manually -->

280 +<!-- see lib/utils/config/definitions.js -->

281 +

282 +#### `bin-links`

283 +

284 +* Default: true

285 +* Type: Boolean

286 +

287 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

288 +executables.

289 +

290 +Set to false to have it not do this. This can be used to work around the

291 +fact that some file systems don't support symlinks, even on ostensibly Unix

292 +systems.

293 +

294 +<!-- automatically generated, do not edit manually -->

295 +<!-- see lib/utils/config/definitions.js -->

296 +

297 +#### `fund`

298 +

299 +* Default: true

300 +* Type: Boolean

301 +

302 +When "true" displays the message at the end of each `npm install`

303 +acknowledging the number of dependencies looking for funding. See [`npm

304 +fund`](/cli/v8/commands/npm-fund) for details.

305 +

306 +<!-- automatically generated, do not edit manually -->

307 +<!-- see lib/utils/config/definitions.js -->

308 +

309 +#### `dry-run`

310 +

311 +* Default: false

312 +* Type: Boolean

313 +

314 +Indicates that you don't want npm to make any changes and that it should

315 +only report what it would have done. This can be passed into any of the

316 +commands that modify your local installation, eg, `install`, `update`,

317 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

318 +

319 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

320 +`owner`, etc.

321 +

322 +<!-- automatically generated, do not edit manually -->

323 +<!-- see lib/utils/config/definitions.js -->

324 +

325 +#### `workspace`

326 +

327 +* Default:

328 +* Type: String (can be set multiple times)

329 +

330 +Enable running a command in the context of the configured workspaces of the

331 +current project while filtering by running only the workspaces defined by

332 +this configuration option.

333 +

334 +Valid values for the `workspace` config are either:

335 +

336 +* Workspace names

337 +* Path to a workspace directory

338 +* Path to a parent workspace directory (will result in selecting all

339 + workspaces within that folder)

340 +

341 +When set for the `npm init` command, this may be set to the folder of a

342 +workspace which does not yet exist, to create the folder and set it up as a

343 +brand new workspace within the project.

344 +

345 +This value is not exported to the environment for child processes.

346 +

347 +<!-- automatically generated, do not edit manually -->

348 +<!-- see lib/utils/config/definitions.js -->

349 +

350 +#### `workspaces`

351 +

352 +* Default: null

353 +* Type: null or Boolean

354 +

355 +Set to true to run the command in the context of **all** configured

356 +workspaces.

357 +

358 +Explicitly setting this to false will cause commands like `install` to

359 +ignore workspaces altogether. When not set explicitly:

360 +

361 +- Commands that operate on the `node_modules` tree (install, update, etc.)

362 +will link workspaces into the `node_modules` folder. - Commands that do

363 +other things (test, exec, publish, etc.) will operate on the root project,

364 +_unless_ one or more workspaces are specified in the `workspace` config.

365 +

366 +This value is not exported to the environment for child processes.

367 +

368 +<!-- automatically generated, do not edit manually -->

369 +<!-- see lib/utils/config/definitions.js -->

370 +

371 +#### `include-workspace-root`

372 +

373 +* Default: false

374 +* Type: Boolean

375 +

376 +Include the workspace root when workspaces are enabled for a command.

377 +

378 +When false, specifying individual workspaces via the `workspace` config, or

379 +all workspaces via the `workspaces` flag, will cause npm to operate only on

380 +the specified workspaces, and not on the root project.

381 +

382 +<!-- automatically generated, do not edit manually -->

383 +<!-- see lib/utils/config/definitions.js -->

384 +

385 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

386 +

387 +### See Also

388 +

389 +* [npm developers](/cli/v8/using-npm/developers)

390 +* [package.json](/cli/v8/configuring-npm/package-json)

391 +* [npm install](/cli/v8/commands/npm-install)

392 +* [npm folders](/cli/v8/configuring-npm/folders)

393 +* [npm config](/cli/v8/commands/npm-config)

394 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-logout.md new

+93

@@ -0,0 +1,93 @@

1 +---

2 +title: npm-logout

3 +section: 1

4 +description: Log out of the registry

5 +redirect_from:

6 + - /cli/logout

7 + - /cli/logout.html

8 + - /cli/commands/logout

9 + - /cli-commands/logout

10 + - /cli-commands/logout.html

11 + - /cli-commands/npm-logout

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-logout.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm logout [--registry=<url>] [--scope=<@scope>]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +When logged into a registry that supports token-based authentication, tell

28 +the server to end this token's session. This will invalidate the token

29 +everywhere you're using it, not just for the current environment.

30 +

31 +When logged into a legacy registry that uses username and password

32 +authentication, this will clear the credentials in your user configuration.

33 +In this case, it will _only_ affect the current environment.

34 +

35 +If `--scope` is provided, this will find the credentials for the registry

36 +connected to that scope, if set.

37 +

38 +### Configuration

39 +

40 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

41 +<!-- automatically generated, do not edit manually -->

42 +<!-- see lib/utils/config/definitions.js -->

43 +#### `registry`

44 +

45 +* Default: "https://registry.npmjs.org/"

46 +* Type: URL

47 +

48 +The base URL of the npm registry.

49 +

50 +<!-- automatically generated, do not edit manually -->

51 +<!-- see lib/utils/config/definitions.js -->

52 +

53 +#### `scope`

54 +

55 +* Default: the scope of the current project, if any, or ""

56 +* Type: String

57 +

58 +Associate an operation with a scope for a scoped registry.

59 +

60 +Useful when logging in to or out of a private registry:

61 +

62 +```

63 +# log in, linking the scope to the custom registry

64 +npm login --scope=@mycorp --registry=https://registry.mycorp.com

65 +

66 +# log out, removing the link and the auth token

67 +npm logout --scope=@mycorp

68 +```

69 +

70 +This will cause `@mycorp` to be mapped to the registry for future

71 +installation of packages specified according to the pattern

72 +`@mycorp/package`.

73 +

74 +This will also cause `npm init` to create a scoped package.

75 +

76 +```

77 +# accept all defaults, and create a package named "@foo/whatever",

78 +# instead of just named "whatever"

79 +npm init --scope=@foo --yes

80 +```

81 +

82 +

83 +<!-- automatically generated, do not edit manually -->

84 +<!-- see lib/utils/config/definitions.js -->

85 +

86 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

87 +

88 +### See Also

89 +

90 +* [npm adduser](/cli/v8/commands/npm-adduser)

91 +* [npm registry](/cli/v8/using-npm/registry)

92 +* [npm config](/cli/v8/commands/npm-config)

93 +* [npm whoami](/cli/v8/commands/npm-whoami)

content/cli/v8/commands/npm-ls.md new

+300

@@ -0,0 +1,300 @@

1 +---

2 +title: npm-ls

3 +section: 1

4 +description: List installed packages

5 +redirect_from:

6 + - /cli/ls

7 + - /cli/ls.html

8 + - /cli/commands/ls

9 + - /cli-commands/ls

10 + - /cli-commands/ls.html

11 + - /cli-commands/npm-ls

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-ls.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm ls [[<@scope>/]<pkg> ...]

21 +

22 +aliases: list, la, ll

23 +```

24 +

25 +### Description

26 +

27 +This command will print to stdout all the versions of packages that are

28 +installed, as well as their dependencies when `--all` is specified, in a

29 +tree structure.

30 +

31 +Note: to get a "bottoms up" view of why a given package is included in the

32 +tree at all, use [`npm explain`](/cli/v8/commands/npm-explain).

33 +

34 +Positional arguments are `name@version-range` identifiers, which will limit

35 +the results to only the paths to the packages named. Note that nested

36 +packages will *also* show the paths to the specified packages. For

37 +example, running `npm ls promzard` in npm's source tree will show:

38 +

39 +```bash

40 +npm@8.0.0 /path/to/npm

41 +└─┬ init-package-json@0.0.4

42 + └── promzard@0.1.5

43 +```

44 +

45 +It will print out extraneous, missing, and invalid packages.

46 +

47 +If a project specifies git urls for dependencies these are shown

48 +in parentheses after the name@version to make it easier for users to

49 +recognize potential forks of a project.

50 +

51 +The tree shown is the logical dependency tree, based on package

52 +dependencies, not the physical layout of your `node_modules` folder.

53 +

54 +When run as `ll` or `la`, it shows extended information by default.

55 +

56 +### Note: Design Changes Pending

57 +

58 +The `npm ls` command's output and behavior made a _ton_ of sense when npm

59 +created a `node_modules` folder that naively nested every dependency. In

60 +such a case, the logical dependency graph and physical tree of packages on

61 +disk would be roughly identical.

62 +

63 +With the advent of automatic install-time deduplication of dependencies in

64 +npm v3, the `ls` output was modified to display the logical dependency

65 +graph as a tree structure, since this was more useful to most users.

66 +However, without using `npm ls -l`, it became impossible show _where_ a

67 +package was actually installed much of the time!

68 +

69 +With the advent of automatic installation of `peerDependencies` in npm v7,

70 +this gets even more curious, as `peerDependencies` are logically

71 +"underneath" their dependents in the dependency graph, but are always

72 +physically at or above their location on disk.

73 +

74 +Also, in the years since npm got an `ls` command (in version 0.0.2!),

75 +dependency graphs have gotten much larger as a general rule. Therefore, in

76 +order to avoid dumping an excessive amount of content to the terminal, `npm

77 +ls` now only shows the _top_ level dependencies, unless `--all` is

78 +provided.

79 +

80 +A thorough re-examination of the use cases, intention, behavior, and output

81 +of this command, is currently underway. Expect significant changes to at

82 +least the default human-readable `npm ls` output in npm v8.

83 +

84 +### Configuration

85 +

86 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

87 +<!-- automatically generated, do not edit manually -->

88 +<!-- see lib/utils/config/definitions.js -->

89 +#### `all`

90 +

91 +* Default: false

92 +* Type: Boolean

93 +

94 +When running `npm outdated` and `npm ls`, setting `--all` will show all

95 +outdated or installed packages, rather than only those directly depended

96 +upon by the current project.

97 +

98 +<!-- automatically generated, do not edit manually -->

99 +<!-- see lib/utils/config/definitions.js -->

100 +

101 +#### `json`

102 +

103 +* Default: false

104 +* Type: Boolean

105 +

106 +Whether or not to output JSON data, rather than the normal output.

107 +

108 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

109 + saving them to your `package.json`.

110 +

111 +Not supported by all npm commands.

112 +

113 +<!-- automatically generated, do not edit manually -->

114 +<!-- see lib/utils/config/definitions.js -->

115 +

116 +#### `long`

117 +

118 +* Default: false

119 +* Type: Boolean

120 +

121 +Show extended information in `ls`, `search`, and `help-search`.

122 +

123 +<!-- automatically generated, do not edit manually -->

124 +<!-- see lib/utils/config/definitions.js -->

125 +

126 +#### `parseable`

127 +

128 +* Default: false

129 +* Type: Boolean

130 +

131 +Output parseable results from commands that write to standard output. For

132 +`npm search`, this will be tab-separated table format.

133 +

134 +<!-- automatically generated, do not edit manually -->

135 +<!-- see lib/utils/config/definitions.js -->

136 +

137 +#### `global`

138 +

139 +* Default: false

140 +* Type: Boolean

141 +

142 +Operates in "global" mode, so that packages are installed into the `prefix`

143 +folder instead of the current working directory. See

144 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

145 +

146 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

147 + of the current working directory.

148 +* bin files are linked to `{prefix}/bin`

149 +* man pages are linked to `{prefix}/share/man`

150 +

151 +<!-- automatically generated, do not edit manually -->

152 +<!-- see lib/utils/config/definitions.js -->

153 +

154 +#### `depth`

155 +

156 +* Default: `Infinity` if `--all` is set, otherwise `1`

157 +* Type: null or Number

158 +

159 +The depth to go when recursing packages for `npm ls`.

160 +

161 +If not set, `npm ls` will show only the immediate dependencies of the root

162 +project. If `--all` is set, then npm will show all dependencies by default.

163 +

164 +<!-- automatically generated, do not edit manually -->

165 +<!-- see lib/utils/config/definitions.js -->

166 +

167 +#### `omit`

168 +

169 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

170 + 'production', otherwise empty.

171 +* Type: "dev", "optional", or "peer" (can be set multiple times)

172 +

173 +Dependency types to omit from the installation tree on disk.

174 +

175 +Note that these dependencies _are_ still resolved and added to the

176 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

177 +physically installed on disk.

178 +

179 +If a package type appears in both the `--include` and `--omit` lists, then

180 +it will be included.

181 +

182 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

183 +variable will be set to `'production'` for all lifecycle scripts.

184 +

185 +<!-- automatically generated, do not edit manually -->

186 +<!-- see lib/utils/config/definitions.js -->

187 +

188 +#### `link`

189 +

190 +* Default: false

191 +* Type: Boolean

192 +

193 +Used with `npm ls`, limiting output to only those packages that are linked.

194 +

195 +<!-- automatically generated, do not edit manually -->

196 +<!-- see lib/utils/config/definitions.js -->

197 +

198 +#### `package-lock-only`

199 +

200 +* Default: false

201 +* Type: Boolean

202 +

203 +If set to true, the current operation will only use the `package-lock.json`,

204 +ignoring `node_modules`.

205 +

206 +For `update` this means only the `package-lock.json` will be updated,

207 +instead of checking `node_modules` and downloading dependencies.

208 +

209 +For `list` this means the output will be based on the tree described by the

210 +`package-lock.json`, rather than the contents of `node_modules`.

211 +

212 +<!-- automatically generated, do not edit manually -->

213 +<!-- see lib/utils/config/definitions.js -->

214 +

215 +#### `unicode`

216 +

217 +* Default: false on windows, true on mac/unix systems with a unicode locale,

218 + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables.

219 +* Type: Boolean

220 +

221 +When set to true, npm uses unicode characters in the tree output. When

222 +false, it uses ascii characters instead of unicode glyphs.

223 +

224 +<!-- automatically generated, do not edit manually -->

225 +<!-- see lib/utils/config/definitions.js -->

226 +

227 +#### `workspace`

228 +

229 +* Default:

230 +* Type: String (can be set multiple times)

231 +

232 +Enable running a command in the context of the configured workspaces of the

233 +current project while filtering by running only the workspaces defined by

234 +this configuration option.

235 +

236 +Valid values for the `workspace` config are either:

237 +

238 +* Workspace names

239 +* Path to a workspace directory

240 +* Path to a parent workspace directory (will result in selecting all

241 + workspaces within that folder)

242 +

243 +When set for the `npm init` command, this may be set to the folder of a

244 +workspace which does not yet exist, to create the folder and set it up as a

245 +brand new workspace within the project.

246 +

247 +This value is not exported to the environment for child processes.

248 +

249 +<!-- automatically generated, do not edit manually -->

250 +<!-- see lib/utils/config/definitions.js -->

251 +

252 +#### `workspaces`

253 +

254 +* Default: null

255 +* Type: null or Boolean

256 +

257 +Set to true to run the command in the context of **all** configured

258 +workspaces.

259 +

260 +Explicitly setting this to false will cause commands like `install` to

261 +ignore workspaces altogether. When not set explicitly:

262 +

263 +- Commands that operate on the `node_modules` tree (install, update, etc.)

264 +will link workspaces into the `node_modules` folder. - Commands that do

265 +other things (test, exec, publish, etc.) will operate on the root project,

266 +_unless_ one or more workspaces are specified in the `workspace` config.

267 +

268 +This value is not exported to the environment for child processes.

269 +

270 +<!-- automatically generated, do not edit manually -->

271 +<!-- see lib/utils/config/definitions.js -->

272 +

273 +#### `include-workspace-root`

274 +

275 +* Default: false

276 +* Type: Boolean

277 +

278 +Include the workspace root when workspaces are enabled for a command.

279 +

280 +When false, specifying individual workspaces via the `workspace` config, or

281 +all workspaces via the `workspaces` flag, will cause npm to operate only on

282 +the specified workspaces, and not on the root project.

283 +

284 +<!-- automatically generated, do not edit manually -->

285 +<!-- see lib/utils/config/definitions.js -->

286 +

287 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

288 +

289 +### See Also

290 +

291 +* [npm explain](/cli/v8/commands/npm-explain)

292 +* [npm config](/cli/v8/commands/npm-config)

293 +* [npmrc](/cli/v8/configuring-npm/npmrc)

294 +* [npm folders](/cli/v8/configuring-npm/folders)

295 +* [npm explain](/cli/v8/commands/npm-explain)

296 +* [npm install](/cli/v8/commands/npm-install)

297 +* [npm link](/cli/v8/commands/npm-link)

298 +* [npm prune](/cli/v8/commands/npm-prune)

299 +* [npm outdated](/cli/v8/commands/npm-outdated)

300 +* [npm update](/cli/v8/commands/npm-update)

content/cli/v8/commands/npm-org.md new

+131

@@ -0,0 +1,131 @@

1 +---

2 +title: npm-org

3 +section: 1

4 +description: Manage orgs

5 +redirect_from:

6 + - /cli/org

7 + - /cli/org.html

8 + - /cli/commands/org

9 + - /cli-commands/org

10 + - /cli-commands/org.html

11 + - /cli-commands/npm-org

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-org.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm org set <orgname> <username> [developer | admin | owner]

21 +npm org rm <orgname> <username>

22 +npm org ls <orgname> [<username>]

23 +```

24 +

25 +Note: This command is unaware of workspaces.

26 +

27 +### Example

28 +

29 +Add a new developer to an org:

30 +

31 +```bash

32 +$ npm org set my-org @mx-smith

33 +```

34 +

35 +Add a new admin to an org (or change a developer to an admin):

36 +

37 +```bash

38 +$ npm org set my-org @mx-santos admin

39 +```

40 +

41 +Remove a user from an org:

42 +

43 +```bash

44 +$ npm org rm my-org mx-santos

45 +```

46 +

47 +List all users in an org:

48 +

49 +```bash

50 +$ npm org ls my-org

51 +```

52 +

53 +List all users in JSON format:

54 +

55 +```bash

56 +$ npm org ls my-org --json

57 +```

58 +

59 +See what role a user has in an org:

60 +

61 +```bash

62 +$ npm org ls my-org @mx-santos

63 +```

64 +

65 +### Description

66 +

67 +You can use the `npm org` commands to manage and view users of an

68 +organization. It supports adding and removing users, changing their roles,

69 +listing them, and finding specific ones and their roles.

70 +

71 +### Configuration

72 +

73 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

74 +<!-- automatically generated, do not edit manually -->

75 +<!-- see lib/utils/config/definitions.js -->

76 +#### `registry`

77 +

78 +* Default: "https://registry.npmjs.org/"

79 +* Type: URL

80 +

81 +The base URL of the npm registry.

82 +

83 +<!-- automatically generated, do not edit manually -->

84 +<!-- see lib/utils/config/definitions.js -->

85 +

86 +#### `otp`

87 +

88 +* Default: null

89 +* Type: null or String

90 +

91 +This is a one-time password from a two-factor authenticator. It's needed

92 +when publishing or changing package permissions with `npm access`.

93 +

94 +If not set, and a registry response fails with a challenge for a one-time

95 +password, npm will prompt on the command line for one.

96 +

97 +<!-- automatically generated, do not edit manually -->

98 +<!-- see lib/utils/config/definitions.js -->

99 +

100 +#### `json`

101 +

102 +* Default: false

103 +* Type: Boolean

104 +

105 +Whether or not to output JSON data, rather than the normal output.

106 +

107 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

108 + saving them to your `package.json`.

109 +

110 +Not supported by all npm commands.

111 +

112 +<!-- automatically generated, do not edit manually -->

113 +<!-- see lib/utils/config/definitions.js -->

114 +

115 +#### `parseable`

116 +

117 +* Default: false

118 +* Type: Boolean

119 +

120 +Output parseable results from commands that write to standard output. For

121 +`npm search`, this will be tab-separated table format.

122 +

123 +<!-- automatically generated, do not edit manually -->

124 +<!-- see lib/utils/config/definitions.js -->

125 +

126 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

127 +

128 +### See Also

129 +

130 +* [using orgs](/cli/v8/using-npm/orgs)

131 +* [Documentation on npm Orgs](https://docs.npmjs.com/orgs/)

content/cli/v8/commands/npm-outdated.md new

+200

@@ -0,0 +1,200 @@

1 +---

2 +title: npm-outdated

3 +section: 1

4 +description: Check for outdated packages

5 +redirect_from:

6 + - /cli/outdated

7 + - /cli/outdated.html

8 + - /cli/commands/outdated

9 + - /cli-commands/outdated

10 + - /cli-commands/outdated.html

11 + - /cli-commands/npm-outdated

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-outdated.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm outdated [[<@scope>/]<pkg> ...]

21 +```

22 +

23 +### Description

24 +

25 +This command will check the registry to see if any (or, specific) installed

26 +packages are currently outdated.

27 +

28 +By default, only the direct dependencies of the root project and direct

29 +dependencies of your configured *workspaces* are shown.

30 +Use `--all` to find all outdated meta-dependencies as well.

31 +

32 +In the output:

33 +

34 +* `wanted` is the maximum version of the package that satisfies the semver

35 + range specified in `package.json`. If there's no available semver range

36 + (i.e. you're running `npm outdated --global`, or the package isn't

37 + included in `package.json`), then `wanted` shows the currently-installed

38 + version.

39 +* `latest` is the version of the package tagged as latest in the registry.

40 + Running `npm publish` with no special configuration will publish the

41 + package with a dist-tag of `latest`. This may or may not be the maximum

42 + version of the package, or the most-recently published version of the

43 + package, depending on how the package's developer manages the latest

44 + [dist-tag](/cli/v8/commands/npm-dist-tag).

45 +* `location` is where in the physical tree the package is located.

46 +* `depended by` shows which package depends on the displayed dependency

47 +* `package type` (when using `--long` / `-l`) tells you whether this

48 + package is a `dependency` or a dev/peer/optional dependency. Packages not

49 + included in `package.json` are always marked `dependencies`.

50 +* `homepage` (when using `--long` / `-l`) is the `homepage` value contained

51 + in the package's packument

52 +* Red means there's a newer version matching your semver requirements, so

53 + you should update now.

54 +* Yellow indicates that there's a newer version _above_ your semver

55 + requirements (usually new major, or new 0.x minor) so proceed with

56 + caution.

57 +

58 +### An example

59 +

60 +```bash

61 +$ npm outdated

62 +Package Current Wanted Latest Location Depended by

63 +glob 5.0.15 5.0.15 6.0.1 node_modules/glob dependent-package-name

64 +nothingness 0.0.3 git git node_modules/nothingness dependent-package-name

65 +npm 3.5.1 3.5.2 3.5.1 node_modules/npm dependent-package-name

66 +local-dev 0.0.3 linked linked local-dev dependent-package-name

67 +once 1.3.2 1.3.3 1.3.3 node_modules/once dependent-package-name

68 +```

69 +

70 +With these `dependencies`:

71 +```json

72 +{

73 + "glob": "^5.0.15",

74 + "nothingness": "github:othiym23/nothingness#master",

75 + "npm": "^3.5.1",

76 + "once": "^1.3.1"

77 +}

78 +```

79 +

80 +A few things to note:

81 +

82 +* `glob` requires `^5`, which prevents npm from installing `glob@6`, which

83 + is outside the semver range.

84 +* Git dependencies will always be reinstalled, because of how they're

85 + specified. The installed committish might satisfy the dependency

86 + specifier (if it's something immutable, like a commit SHA), or it might

87 + not, so `npm outdated` and `npm update` have to fetch Git repos to check.

88 + This is why currently doing a reinstall of a Git dependency always forces

89 + a new clone and install.

90 +* `npm@3.5.2` is marked as "wanted", but "latest" is `npm@3.5.1` because

91 + npm uses dist-tags to manage its `latest` and `next` release channels.

92 + `npm update` will install the _newest_ version, but `npm install npm`

93 + (with no semver range) will install whatever's tagged as `latest`.

94 +* `once` is just plain out of date. Reinstalling `node_modules` from

95 + scratch or running `npm update` will bring it up to spec.

96 +

97 +### Configuration

98 +

99 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

100 +<!-- automatically generated, do not edit manually -->

101 +<!-- see lib/utils/config/definitions.js -->

102 +#### `all`

103 +

104 +* Default: false

105 +* Type: Boolean

106 +

107 +When running `npm outdated` and `npm ls`, setting `--all` will show all

108 +outdated or installed packages, rather than only those directly depended

109 +upon by the current project.

110 +

111 +<!-- automatically generated, do not edit manually -->

112 +<!-- see lib/utils/config/definitions.js -->

113 +

114 +#### `json`

115 +

116 +* Default: false

117 +* Type: Boolean

118 +

119 +Whether or not to output JSON data, rather than the normal output.

120 +

121 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

122 + saving them to your `package.json`.

123 +

124 +Not supported by all npm commands.

125 +

126 +<!-- automatically generated, do not edit manually -->

127 +<!-- see lib/utils/config/definitions.js -->

128 +

129 +#### `long`

130 +

131 +* Default: false

132 +* Type: Boolean

133 +

134 +Show extended information in `ls`, `search`, and `help-search`.

135 +

136 +<!-- automatically generated, do not edit manually -->

137 +<!-- see lib/utils/config/definitions.js -->

138 +

139 +#### `parseable`

140 +

141 +* Default: false

142 +* Type: Boolean

143 +

144 +Output parseable results from commands that write to standard output. For

145 +`npm search`, this will be tab-separated table format.

146 +

147 +<!-- automatically generated, do not edit manually -->

148 +<!-- see lib/utils/config/definitions.js -->

149 +

150 +#### `global`

151 +

152 +* Default: false

153 +* Type: Boolean

154 +

155 +Operates in "global" mode, so that packages are installed into the `prefix`

156 +folder instead of the current working directory. See

157 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

158 +

159 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

160 + of the current working directory.

161 +* bin files are linked to `{prefix}/bin`

162 +* man pages are linked to `{prefix}/share/man`

163 +

164 +<!-- automatically generated, do not edit manually -->

165 +<!-- see lib/utils/config/definitions.js -->

166 +

167 +#### `workspace`

168 +

169 +* Default:

170 +* Type: String (can be set multiple times)

171 +

172 +Enable running a command in the context of the configured workspaces of the

173 +current project while filtering by running only the workspaces defined by

174 +this configuration option.

175 +

176 +Valid values for the `workspace` config are either:

177 +

178 +* Workspace names

179 +* Path to a workspace directory

180 +* Path to a parent workspace directory (will result in selecting all

181 + workspaces within that folder)

182 +

183 +When set for the `npm init` command, this may be set to the folder of a

184 +workspace which does not yet exist, to create the folder and set it up as a

185 +brand new workspace within the project.

186 +

187 +This value is not exported to the environment for child processes.

188 +

189 +<!-- automatically generated, do not edit manually -->

190 +<!-- see lib/utils/config/definitions.js -->

191 +

192 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

193 +

194 +### See Also

195 +

196 +* [npm update](/cli/v8/commands/npm-update)

197 +* [npm dist-tag](/cli/v8/commands/npm-dist-tag)

198 +* [npm registry](/cli/v8/using-npm/registry)

199 +* [npm folders](/cli/v8/configuring-npm/folders)

200 +* [npm workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-owner.md new

+84

@@ -0,0 +1,84 @@

1 +---

2 +title: npm-owner

3 +section: 1

4 +description: Manage package owners

5 +redirect_from:

6 + - /cli/owner

7 + - /cli/owner.html

8 + - /cli/commands/owner

9 + - /cli-commands/owner

10 + - /cli-commands/owner.html

11 + - /cli-commands/npm-owner

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-owner.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm owner add <user> [<@scope>/]<pkg>

21 +npm owner rm <user> [<@scope>/]<pkg>

22 +npm owner ls [<@scope>/]<pkg>

23 +

24 +aliases: author

25 +```

26 +

27 +Note: This command is unaware of workspaces.

28 +

29 +### Description

30 +

31 +Manage ownership of published packages.

32 +

33 +* ls: List all the users who have access to modify a package and push new

34 + versions. Handy when you need to know who to bug for help.

35 +* add: Add a new user as a maintainer of a package. This user is enabled

36 + to modify metadata, publish new versions, and add other owners.

37 +* rm: Remove a user from the package owner list. This immediately revokes

38 + their privileges.

39 +

40 +Note that there is only one level of access. Either you can modify a package,

41 +or you can't. Future versions may contain more fine-grained access levels, but

42 +that is not implemented at this time.

43 +

44 +If you have two-factor authentication enabled with `auth-and-writes` (see

45 +[`npm-profile`](/cli/v8/commands/npm-profile)) then you'll need to include an otp

46 +on the command line when changing ownership with `--otp`.

47 +

48 +### Configuration

49 +

50 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

51 +<!-- automatically generated, do not edit manually -->

52 +<!-- see lib/utils/config/definitions.js -->

53 +#### `registry`

54 +

55 +* Default: "https://registry.npmjs.org/"

56 +* Type: URL

57 +

58 +The base URL of the npm registry.

59 +

60 +<!-- automatically generated, do not edit manually -->

61 +<!-- see lib/utils/config/definitions.js -->

62 +

63 +#### `otp`

64 +

65 +* Default: null

66 +* Type: null or String

67 +

68 +This is a one-time password from a two-factor authenticator. It's needed

69 +when publishing or changing package permissions with `npm access`.

70 +

71 +If not set, and a registry response fails with a challenge for a one-time

72 +password, npm will prompt on the command line for one.

73 +

74 +<!-- automatically generated, do not edit manually -->

75 +<!-- see lib/utils/config/definitions.js -->

76 +

77 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

78 +

79 +### See Also

80 +

81 +* [npm profile](/cli/v8/commands/npm-profile)

82 +* [npm publish](/cli/v8/commands/npm-publish)

83 +* [npm registry](/cli/v8/using-npm/registry)

84 +* [npm adduser](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm-pack.md new

+150

@@ -0,0 +1,150 @@

1 +---

2 +title: npm-pack

3 +section: 1

4 +description: Create a tarball from a package

5 +redirect_from:

6 + - /cli/pack

7 + - /cli/pack.html

8 + - /cli/commands/pack

9 + - /cli-commands/pack

10 + - /cli-commands/pack.html

11 + - /cli-commands/npm-pack

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-pack.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm pack [[<@scope>/]<pkg>...] [--dry-run] [--json]

21 +```

22 +

23 +### Configuration

24 +

25 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

26 +<!-- automatically generated, do not edit manually -->

27 +<!-- see lib/utils/config/definitions.js -->

28 +#### `dry-run`

29 +

30 +* Default: false

31 +* Type: Boolean

32 +

33 +Indicates that you don't want npm to make any changes and that it should

34 +only report what it would have done. This can be passed into any of the

35 +commands that modify your local installation, eg, `install`, `update`,

36 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

37 +

38 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

39 +`owner`, etc.

40 +

41 +<!-- automatically generated, do not edit manually -->

42 +<!-- see lib/utils/config/definitions.js -->

43 +

44 +#### `json`

45 +

46 +* Default: false

47 +* Type: Boolean

48 +

49 +Whether or not to output JSON data, rather than the normal output.

50 +

51 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

52 + saving them to your `package.json`.

53 +

54 +Not supported by all npm commands.

55 +

56 +<!-- automatically generated, do not edit manually -->

57 +<!-- see lib/utils/config/definitions.js -->

58 +

59 +#### `pack-destination`

60 +

61 +* Default: "."

62 +* Type: String

63 +

64 +Directory in which `npm pack` will save tarballs.

65 +

66 +<!-- automatically generated, do not edit manually -->

67 +<!-- see lib/utils/config/definitions.js -->

68 +

69 +#### `workspace`

70 +

71 +* Default:

72 +* Type: String (can be set multiple times)

73 +

74 +Enable running a command in the context of the configured workspaces of the

75 +current project while filtering by running only the workspaces defined by

76 +this configuration option.

77 +

78 +Valid values for the `workspace` config are either:

79 +

80 +* Workspace names

81 +* Path to a workspace directory

82 +* Path to a parent workspace directory (will result in selecting all

83 + workspaces within that folder)

84 +

85 +When set for the `npm init` command, this may be set to the folder of a

86 +workspace which does not yet exist, to create the folder and set it up as a

87 +brand new workspace within the project.

88 +

89 +This value is not exported to the environment for child processes.

90 +

91 +<!-- automatically generated, do not edit manually -->

92 +<!-- see lib/utils/config/definitions.js -->

93 +

94 +#### `workspaces`

95 +

96 +* Default: null

97 +* Type: null or Boolean

98 +

99 +Set to true to run the command in the context of **all** configured

100 +workspaces.

101 +

102 +Explicitly setting this to false will cause commands like `install` to

103 +ignore workspaces altogether. When not set explicitly:

104 +

105 +- Commands that operate on the `node_modules` tree (install, update, etc.)

106 +will link workspaces into the `node_modules` folder. - Commands that do

107 +other things (test, exec, publish, etc.) will operate on the root project,

108 +_unless_ one or more workspaces are specified in the `workspace` config.

109 +

110 +This value is not exported to the environment for child processes.

111 +

112 +<!-- automatically generated, do not edit manually -->

113 +<!-- see lib/utils/config/definitions.js -->

114 +

115 +#### `include-workspace-root`

116 +

117 +* Default: false

118 +* Type: Boolean

119 +

120 +Include the workspace root when workspaces are enabled for a command.

121 +

122 +When false, specifying individual workspaces via the `workspace` config, or

123 +all workspaces via the `workspaces` flag, will cause npm to operate only on

124 +the specified workspaces, and not on the root project.

125 +

126 +<!-- automatically generated, do not edit manually -->

127 +<!-- see lib/utils/config/definitions.js -->

128 +

129 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

130 +

131 +### Description

132 +

133 +For anything that's installable (that is, a package folder, tarball,

134 +tarball url, git url, name@tag, name@version, name, or scoped name), this

135 +command will fetch it to the cache, copy the tarball to the current working

136 +directory as `<name>-<version>.tgz`, and then write the filenames out to

137 +stdout.

138 +

139 +If the same package is specified multiple times, then the file will be

140 +overwritten the second time.

141 +

142 +If no arguments are supplied, then npm packs the current package folder.

143 +

144 +### See Also

145 +

146 +* [npm-packlist package](http://npm.im/npm-packlist)

147 +* [npm cache](/cli/v8/commands/npm-cache)

148 +* [npm publish](/cli/v8/commands/npm-publish)

149 +* [npm config](/cli/v8/commands/npm-config)

150 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-ping.md new

+59

@@ -0,0 +1,59 @@

1 +---

2 +title: npm-ping

3 +section: 1

4 +description: Ping npm registry

5 +redirect_from:

6 + - /cli/ping

7 + - /cli/ping.html

8 + - /cli/commands/ping

9 + - /cli-commands/ping

10 + - /cli-commands/ping.html

11 + - /cli-commands/npm-ping

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-ping.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm ping [--registry <registry>]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Ping the configured or given npm registry and verify authentication.

28 +If it works it will output something like:

29 +

30 +```bash

31 +Ping success: {*Details about registry*}

32 +```

33 +otherwise you will get:

34 +```bash

35 +Ping error: {*Detail about error}

36 +```

37 +

38 +### Configuration

39 +

40 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

41 +<!-- automatically generated, do not edit manually -->

42 +<!-- see lib/utils/config/definitions.js -->

43 +#### `registry`

44 +

45 +* Default: "https://registry.npmjs.org/"

46 +* Type: URL

47 +

48 +The base URL of the npm registry.

49 +

50 +<!-- automatically generated, do not edit manually -->

51 +<!-- see lib/utils/config/definitions.js -->

52 +

53 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

54 +

55 +### See Also

56 +

57 +* [npm doctor](/cli/v8/commands/npm-doctor)

58 +* [npm config](/cli/v8/commands/npm-config)

59 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-pkg.md new

+276

@@ -0,0 +1,276 @@

1 +---

2 +title: npm-pkg

3 +section: 1

4 +description: Manages your package.json

5 +redirect_from:

6 + - /cli/pkg

7 + - /cli/pkg.html

8 + - /cli/commands/pkg

9 + - /cli-commands/pkg

10 + - /cli-commands/pkg.html

11 + - /cli-commands/npm-pkg

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-pkg.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm pkg get [<field> [.<subfield> ...]]

21 +npm pkg set <field>=<value> [.<subfield>=<value> ...]

22 +npm pkg delete <field> [.<subfield> ...]

23 +```

24 +

25 +### Description

26 +

27 +A command that automates the management of `package.json` files.

28 +`npm pkg` provide 3 different sub commands that allow you to modify or retrieve

29 +values for given object keys in your `package.json`.

30 +

31 +The syntax to retrieve and set fields is a dot separated representation of

32 +the nested object properties to be found within your `package.json`, it's the

33 +same notation used in [`npm view`](/cli/v8/commands/npm-view) to retrieve information

34 +from the registry manifest, below you can find more examples on how to use it.

35 +

36 +Returned values are always in **json** format.

37 +

38 +* `npm pkg get <field>`

39 +

40 + Retrieves a value `key`, defined in your `package.json` file.

41 +

42 + For example, in order to retrieve the name of the current package, you

43 + can run:

44 +

45 + ```bash

46 + npm pkg get name

47 + ```

48 +

49 + It's also possible to retrieve multiple values at once:

50 +

51 + ```bash

52 + npm pkg get name version

53 + ```

54 +

55 + You can view child fields by separating them with a period. To retrieve

56 + the value of a test `script` value, you would run the following command:

57 +

58 + ```bash

59 + npm pkg get scripts.test

60 + ```

61 +

62 + For fields that are arrays, requesting a non-numeric field will return

63 + all of the values from the objects in the list. For example, to get all

64 + the contributor emails for a package, you would run:

65 +

66 + ```bash

67 + npm pkg get contributors.email

68 + ```

69 +

70 + You may also use numeric indices in square braces to specifically select

71 + an item in an array field. To just get the email address of the first

72 + contributor in the list, you can run:

73 +

74 + ```bash

75 + npm pkg get contributors[0].email

76 + ```

77 +

78 +* `npm pkg set <field>=<value>`

79 +

80 + Sets a `value` in your `package.json` based on the `field` value. When

81 + saving to your `package.json` file the same set of rules used during

82 + `npm install` and other cli commands that touches the `package.json` file

83 + are used, making sure to respect the existing indentation and possibly

84 + applying some validation prior to saving values to the file.

85 +

86 + The same syntax used to retrieve values from your package can also be used

87 + to define new properties or overriding existing ones, below are some

88 + examples of how the dot separated syntax can be used to edit your

89 + `package.json` file.

90 +

91 + Defining a new bin named `mynewcommand` in your `package.json` that points

92 + to a file `cli.js`:

93 +

94 + ```bash

95 + npm pkg set bin.mynewcommand=cli.js

96 + ```

97 +

98 + Setting multiple fields at once is also possible:

99 +

100 + ```bash

101 + npm pkg set description='Awesome package' engines.node='>=10'

102 + ```

103 +

104 + It's also possible to add to array values, for example to add a new

105 + contributor entry:

106 +

107 + ```bash

108 + npm pkg set contributors[0].name='Foo' contributors[0].email='foo@bar.ca'

109 + ```

110 +

111 + You may also append items to the end of an array using the special

112 + empty bracket notation:

113 +

114 + ```bash

115 + npm pkg set contributors[].name='Foo' contributors[].name='Bar'

116 + ```

117 +

118 + It's also possible to parse values as json prior to saving them to your

119 + `package.json` file, for example in order to set a `"private": true`

120 + property:

121 +

122 + ```bash

123 + npm pkg set private=true --json

124 + ```

125 +

126 + It also enables saving values as numbers:

127 +

128 + ```bash

129 + npm pkg set tap.timeout=60 --json

130 + ```

131 +

132 +* `npm pkg delete <key>`

133 +

134 + Deletes a `key` from your `package.json`

135 +

136 + The same syntax used to set values from your package can also be used

137 + to remove existing ones. For example, in order to remove a script named

138 + build:

139 +

140 + ```bash

141 + npm pkg delete scripts.build

142 + ```

143 +

144 +### Workspaces support

145 +

146 +You can set/get/delete items across your configured workspaces by using the

147 +`workspace` or `workspaces` config options.

148 +

149 +For example, setting a `funding` value across all configured workspaces

150 +of a project:

151 +

152 +```bash

153 +npm pkg set funding=https://example.com --ws

154 +```

155 +

156 +When using `npm pkg get` to retrieve info from your configured workspaces, the

157 +returned result will be in a json format in which top level keys are the

158 +names of each workspace, the values of these keys will be the result values

159 +returned from each of the configured workspaces, e.g:

160 +

161 +```

162 +npm pkg get name version --ws

163 +{

164 + "a": {

165 + "name": "a",

166 + "version": "1.0.0"

167 + },

168 + "b": {

169 + "name": "b",

170 + "version": "1.0.0"

171 + }

172 +}

173 +```

174 +

175 +### Configuration

176 +

177 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

178 +<!-- automatically generated, do not edit manually -->

179 +<!-- see lib/utils/config/definitions.js -->

180 +#### `force`

181 +

182 +* Default: false

183 +* Type: Boolean

184 +

185 +Removes various protections against unfortunate side effects, common

186 +mistakes, unnecessary performance degradation, and malicious input.

187 +

188 +* Allow clobbering non-npm files in global installs.

189 +* Allow the `npm version` command to work on an unclean git repository.

190 +* Allow deleting the cache folder with `npm cache clean`.

191 +* Allow installing packages that have an `engines` declaration requiring a

192 + different version of npm.

193 +* Allow installing packages that have an `engines` declaration requiring a

194 + different version of `node`, even if `--engine-strict` is enabled.

195 +* Allow `npm audit fix` to install modules outside your stated dependency

196 + range (including SemVer-major changes).

197 +* Allow unpublishing all versions of a published package.

198 +* Allow conflicting peerDependencies to be installed in the root project.

199 +* Implicitly set `--yes` during `npm init`.

200 +* Allow clobbering existing values in `npm pkg`

201 +

202 +If you don't have a clear idea of what you want to do, it is strongly

203 +recommended that you do not use this option!

204 +

205 +<!-- automatically generated, do not edit manually -->

206 +<!-- see lib/utils/config/definitions.js -->

207 +

208 +#### `json`

209 +

210 +* Default: false

211 +* Type: Boolean

212 +

213 +Whether or not to output JSON data, rather than the normal output.

214 +

215 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

216 + saving them to your `package.json`.

217 +

218 +Not supported by all npm commands.

219 +

220 +<!-- automatically generated, do not edit manually -->

221 +<!-- see lib/utils/config/definitions.js -->

222 +

223 +#### `workspace`

224 +

225 +* Default:

226 +* Type: String (can be set multiple times)

227 +

228 +Enable running a command in the context of the configured workspaces of the

229 +current project while filtering by running only the workspaces defined by

230 +this configuration option.

231 +

232 +Valid values for the `workspace` config are either:

233 +

234 +* Workspace names

235 +* Path to a workspace directory

236 +* Path to a parent workspace directory (will result in selecting all

237 + workspaces within that folder)

238 +

239 +When set for the `npm init` command, this may be set to the folder of a

240 +workspace which does not yet exist, to create the folder and set it up as a

241 +brand new workspace within the project.

242 +

243 +This value is not exported to the environment for child processes.

244 +

245 +<!-- automatically generated, do not edit manually -->

246 +<!-- see lib/utils/config/definitions.js -->

247 +

248 +#### `workspaces`

249 +

250 +* Default: null

251 +* Type: null or Boolean

252 +

253 +Set to true to run the command in the context of **all** configured

254 +workspaces.

255 +

256 +Explicitly setting this to false will cause commands like `install` to

257 +ignore workspaces altogether. When not set explicitly:

258 +

259 +- Commands that operate on the `node_modules` tree (install, update, etc.)

260 +will link workspaces into the `node_modules` folder. - Commands that do

261 +other things (test, exec, publish, etc.) will operate on the root project,

262 +_unless_ one or more workspaces are specified in the `workspace` config.

263 +

264 +This value is not exported to the environment for child processes.

265 +

266 +<!-- automatically generated, do not edit manually -->

267 +<!-- see lib/utils/config/definitions.js -->

268 +

269 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

270 +## See Also

271 +

272 +* [npm install](/cli/v8/commands/npm-install)

273 +* [npm init](/cli/v8/commands/npm-init)

274 +* [npm config](/cli/v8/commands/npm-config)

275 +* [npm set-script](/cli/v8/commands/npm-set-script)

276 +* [workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-prefix.md new

+76

@@ -0,0 +1,76 @@

1 +---

2 +title: npm-prefix

3 +section: 1

4 +description: Display prefix

5 +redirect_from:

6 + - /cli/prefix

7 + - /cli/prefix.html

8 + - /cli/commands/prefix

9 + - /cli-commands/prefix

10 + - /cli-commands/prefix.html

11 + - /cli-commands/npm-prefix

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-prefix.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm prefix [-g]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Print the local prefix to standard output. This is the closest parent directory

28 +to contain a `package.json` file or `node_modules` directory, unless `-g` is

29 +also specified.

30 +

31 +If `-g` is specified, this will be the value of the global prefix. See

32 +[`npm config`](/cli/v8/commands/npm-config) for more detail.

33 +

34 +### Example

35 +

36 +```bash

37 +npm prefix

38 +/usr/local/projects/foo

39 +```

40 +

41 +```bash

42 +npm prefix -g

43 +/usr/local

44 +```

45 +

46 +### Configuration

47 +

48 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

49 +<!-- automatically generated, do not edit manually -->

50 +<!-- see lib/utils/config/definitions.js -->

51 +#### `global`

52 +

53 +* Default: false

54 +* Type: Boolean

55 +

56 +Operates in "global" mode, so that packages are installed into the `prefix`

57 +folder instead of the current working directory. See

58 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

59 +

60 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

61 + of the current working directory.

62 +* bin files are linked to `{prefix}/bin`

63 +* man pages are linked to `{prefix}/share/man`

64 +

65 +<!-- automatically generated, do not edit manually -->

66 +<!-- see lib/utils/config/definitions.js -->

67 +

68 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

69 +

70 +### See Also

71 +

72 +* [npm root](/cli/v8/commands/npm-root)

73 +* [npm bin](/cli/v8/commands/npm-bin)

74 +* [npm folders](/cli/v8/configuring-npm/folders)

75 +* [npm config](/cli/v8/commands/npm-config)

76 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-profile.md new

+151

@@ -0,0 +1,151 @@

1 +---

2 +title: npm-profile

3 +section: 1

4 +description: Change settings on your registry profile

5 +redirect_from:

6 + - /cli/profile

7 + - /cli/profile.html

8 + - /cli/commands/profile

9 + - /cli-commands/profile

10 + - /cli-commands/profile.html

11 + - /cli-commands/npm-profile

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-profile.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm profile get [--json|--parseable] [<property>]

21 +npm profile set [--json|--parseable] <property> <value>

22 +npm profile set password

23 +npm profile enable-2fa [auth-and-writes|auth-only]

24 +npm profile disable-2fa

25 +```

26 +

27 +Note: This command is unaware of workspaces.

28 +

29 +### Description

30 +

31 +Change your profile information on the registry. Note that this command

32 +depends on the registry implementation, so third-party registries may not

33 +support this interface.

34 +

35 +* `npm profile get [<property>]`: Display all of the properties of your

36 + profile, or one or more specific properties. It looks like:

37 +

38 +```bash

39 ++-----------------+---------------------------+

40 +| name | example |

41 ++-----------------+---------------------------+

42 +| email | me@example.com (verified) |

43 ++-----------------+---------------------------+

44 +| two factor auth | auth-and-writes |

45 ++-----------------+---------------------------+

46 +| fullname | Example User |

47 ++-----------------+---------------------------+

48 +| homepage | |

49 ++-----------------+---------------------------+

50 +| freenode | |

51 ++-----------------+---------------------------+

52 +| twitter | |

53 ++-----------------+---------------------------+

54 +| github | |

55 ++-----------------+---------------------------+

56 +| created | 2015-02-26T01:38:35.892Z |

57 ++-----------------+---------------------------+

58 +| updated | 2017-10-02T21:29:45.922Z |

59 ++-----------------+---------------------------+

60 +```

61 +

62 +* `npm profile set <property> <value>`: Set the value of a profile

63 + property. You can set the following properties this way: email, fullname,

64 + homepage, freenode, twitter, github

65 +

66 +* `npm profile set password`: Change your password. This is interactive,

67 + you'll be prompted for your current password and a new password. You'll

68 + also be prompted for an OTP if you have two-factor authentication

69 + enabled.

70 +

71 +* `npm profile enable-2fa [auth-and-writes|auth-only]`: Enables two-factor

72 + authentication. Defaults to `auth-and-writes` mode. Modes are:

73 + * `auth-only`: Require an OTP when logging in or making changes to your

74 + account's authentication. The OTP will be required on both the website

75 + and the command line.

76 + * `auth-and-writes`: Requires an OTP at all the times `auth-only` does,

77 + and also requires one when publishing a module, setting the `latest`

78 + dist-tag, or changing access via `npm access` and `npm owner`.

79 +

80 +* `npm profile disable-2fa`: Disables two-factor authentication.

81 +

82 +### Details

83 +

84 +Some of these commands may not be available on non npmjs.com registries.

85 +

86 +### Configuration

87 +

88 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

89 +<!-- automatically generated, do not edit manually -->

90 +<!-- see lib/utils/config/definitions.js -->

91 +#### `registry`

92 +

93 +* Default: "https://registry.npmjs.org/"

94 +* Type: URL

95 +

96 +The base URL of the npm registry.

97 +

98 +<!-- automatically generated, do not edit manually -->

99 +<!-- see lib/utils/config/definitions.js -->

100 +

101 +#### `json`

102 +

103 +* Default: false

104 +* Type: Boolean

105 +

106 +Whether or not to output JSON data, rather than the normal output.

107 +

108 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

109 + saving them to your `package.json`.

110 +

111 +Not supported by all npm commands.

112 +

113 +<!-- automatically generated, do not edit manually -->

114 +<!-- see lib/utils/config/definitions.js -->

115 +

116 +#### `parseable`

117 +

118 +* Default: false

119 +* Type: Boolean

120 +

121 +Output parseable results from commands that write to standard output. For

122 +`npm search`, this will be tab-separated table format.

123 +

124 +<!-- automatically generated, do not edit manually -->

125 +<!-- see lib/utils/config/definitions.js -->

126 +

127 +#### `otp`

128 +

129 +* Default: null

130 +* Type: null or String

131 +

132 +This is a one-time password from a two-factor authenticator. It's needed

133 +when publishing or changing package permissions with `npm access`.

134 +

135 +If not set, and a registry response fails with a challenge for a one-time

136 +password, npm will prompt on the command line for one.

137 +

138 +<!-- automatically generated, do not edit manually -->

139 +<!-- see lib/utils/config/definitions.js -->

140 +

141 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

142 +

143 +### See Also

144 +

145 +* [npm adduser](/cli/v8/commands/npm-adduser)

146 +* [npm registry](/cli/v8/using-npm/registry)

147 +* [npm config](/cli/v8/commands/npm-config)

148 +* [npmrc](/cli/v8/configuring-npm/npmrc)

149 +* [npm owner](/cli/v8/commands/npm-owner)

150 +* [npm whoami](/cli/v8/commands/npm-whoami)

151 +* [npm token](/cli/v8/commands/npm-token)

content/cli/v8/commands/npm-prune.md new

+169

@@ -0,0 +1,169 @@

1 +---

2 +title: npm-prune

3 +section: 1

4 +description: Remove extraneous packages

5 +redirect_from:

6 + - /cli/prune

7 + - /cli/prune.html

8 + - /cli/commands/prune

9 + - /cli-commands/prune

10 + - /cli-commands/prune.html

11 + - /cli-commands/npm-prune

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-prune.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm prune [[<@scope>/]<pkg>...] [--production] [--dry-run] [--json]

21 +```

22 +

23 +### Description

24 +

25 +This command removes "extraneous" packages. If a package name is provided,

26 +then only packages matching one of the supplied names are removed.

27 +

28 +Extraneous packages are those present in the `node_modules` folder that are

29 +not listed as any package's dependency list.

30 +

31 +If the `--production` flag is specified or the `NODE_ENV` environment

32 +variable is set to `production`, this command will remove the packages

33 +specified in your `devDependencies`. Setting `--no-production` will negate

34 +`NODE_ENV` being set to `production`.

35 +

36 +If the `--dry-run` flag is used then no changes will actually be made.

37 +

38 +If the `--json` flag is used, then the changes `npm prune` made (or would

39 +have made with `--dry-run`) are printed as a JSON object.

40 +

41 +In normal operation, extraneous modules are pruned automatically, so you'll

42 +only need this command with the `--production` flag. However, in the real

43 +world, operation is not always "normal". When crashes or mistakes happen,

44 +this command can help clean up any resulting garbage.

45 +

46 +### Configuration

47 +

48 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

49 +<!-- automatically generated, do not edit manually -->

50 +<!-- see lib/utils/config/definitions.js -->

51 +#### `omit`

52 +

53 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

54 + 'production', otherwise empty.

55 +* Type: "dev", "optional", or "peer" (can be set multiple times)

56 +

57 +Dependency types to omit from the installation tree on disk.

58 +

59 +Note that these dependencies _are_ still resolved and added to the

60 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

61 +physically installed on disk.

62 +

63 +If a package type appears in both the `--include` and `--omit` lists, then

64 +it will be included.

65 +

66 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

67 +variable will be set to `'production'` for all lifecycle scripts.

68 +

69 +<!-- automatically generated, do not edit manually -->

70 +<!-- see lib/utils/config/definitions.js -->

71 +

72 +#### `dry-run`

73 +

74 +* Default: false

75 +* Type: Boolean

76 +

77 +Indicates that you don't want npm to make any changes and that it should

78 +only report what it would have done. This can be passed into any of the

79 +commands that modify your local installation, eg, `install`, `update`,

80 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

81 +

82 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

83 +`owner`, etc.

84 +

85 +<!-- automatically generated, do not edit manually -->

86 +<!-- see lib/utils/config/definitions.js -->

87 +

88 +#### `json`

89 +

90 +* Default: false

91 +* Type: Boolean

92 +

93 +Whether or not to output JSON data, rather than the normal output.

94 +

95 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

96 + saving them to your `package.json`.

97 +

98 +Not supported by all npm commands.

99 +

100 +<!-- automatically generated, do not edit manually -->

101 +<!-- see lib/utils/config/definitions.js -->

102 +

103 +#### `workspace`

104 +

105 +* Default:

106 +* Type: String (can be set multiple times)

107 +

108 +Enable running a command in the context of the configured workspaces of the

109 +current project while filtering by running only the workspaces defined by

110 +this configuration option.

111 +

112 +Valid values for the `workspace` config are either:

113 +

114 +* Workspace names

115 +* Path to a workspace directory

116 +* Path to a parent workspace directory (will result in selecting all

117 + workspaces within that folder)

118 +

119 +When set for the `npm init` command, this may be set to the folder of a

120 +workspace which does not yet exist, to create the folder and set it up as a

121 +brand new workspace within the project.

122 +

123 +This value is not exported to the environment for child processes.

124 +

125 +<!-- automatically generated, do not edit manually -->

126 +<!-- see lib/utils/config/definitions.js -->

127 +

128 +#### `workspaces`

129 +

130 +* Default: null

131 +* Type: null or Boolean

132 +

133 +Set to true to run the command in the context of **all** configured

134 +workspaces.

135 +

136 +Explicitly setting this to false will cause commands like `install` to

137 +ignore workspaces altogether. When not set explicitly:

138 +

139 +- Commands that operate on the `node_modules` tree (install, update, etc.)

140 +will link workspaces into the `node_modules` folder. - Commands that do

141 +other things (test, exec, publish, etc.) will operate on the root project,

142 +_unless_ one or more workspaces are specified in the `workspace` config.

143 +

144 +This value is not exported to the environment for child processes.

145 +

146 +<!-- automatically generated, do not edit manually -->

147 +<!-- see lib/utils/config/definitions.js -->

148 +

149 +#### `include-workspace-root`

150 +

151 +* Default: false

152 +* Type: Boolean

153 +

154 +Include the workspace root when workspaces are enabled for a command.

155 +

156 +When false, specifying individual workspaces via the `workspace` config, or

157 +all workspaces via the `workspaces` flag, will cause npm to operate only on

158 +the specified workspaces, and not on the root project.

159 +

160 +<!-- automatically generated, do not edit manually -->

161 +<!-- see lib/utils/config/definitions.js -->

162 +

163 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

164 +

165 +### See Also

166 +

167 +* [npm uninstall](/cli/v8/commands/npm-uninstall)

168 +* [npm folders](/cli/v8/configuring-npm/folders)

169 +* [npm ls](/cli/v8/commands/npm-ls)

content/cli/v8/commands/npm-publish.md new

+260

@@ -0,0 +1,260 @@

1 +---

2 +title: npm-publish

3 +section: 1

4 +description: Publish a package

5 +redirect_from:

6 + - /cli/publish

7 + - /cli/publish.html

8 + - /cli/commands/publish

9 + - /cli-commands/publish

10 + - /cli-commands/publish.html

11 + - /cli-commands/npm-publish

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-publish.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm publish [<tarball>|<folder>] [--tag <tag>] [--access <public|restricted>] [--otp otpcode] [--dry-run]

21 +

22 +Publishes '.' if no argument supplied

23 +Sets tag 'latest' if no --tag specified

24 +```

25 +

26 +### Description

27 +

28 +Publishes a package to the registry so that it can be installed by name.

29 +

30 +By default npm will publish to the public registry. This can be overridden

31 +by specifying a different default registry or using a

32 +[`scope`](/cli/v8/using-npm/scope) in the name (see

33 +[`package.json`](/cli/v8/configuring-npm/package-json)).

34 +

35 +* `<folder>`: A folder containing a package.json file

36 +

37 +* `<tarball>`: A url or file path to a gzipped tar archive containing a

38 + single folder with a package.json file inside.

39 +

40 +* `[--tag <tag>]`: Registers the published package with the given tag, such

41 + that `npm install <name>@<tag>` will install this version. By default,

42 + `npm publish` updates and `npm install` installs the `latest` tag. See

43 + [`npm-dist-tag`](npm-dist-tag) for details about tags.

44 +

45 +* `[--access <public|restricted>]`: Tells the registry whether this package

46 + should be published as public or restricted. Only applies to scoped

47 + packages, which default to `restricted`. If you don't have a paid

48 + account, you must publish with `--access public` to publish scoped

49 + packages.

50 +

51 +* `[--otp <otpcode>]`: If you have two-factor authentication enabled in

52 + `auth-and-writes` mode then you can provide a code from your

53 + authenticator with this. If you don't include this and you're running

54 + from a TTY then you'll be prompted.

55 +

56 +* `[--dry-run]`: As of `npm@6`, does everything publish would do except

57 + actually publishing to the registry. Reports the details of what would

58 + have been published.

59 +

60 +* `[--workspaces]`: Enables workspace context while publishing. All

61 + workspace packages will be published.

62 +

63 +* `[--workspace]`: Enables workspaces context and limits results to only

64 + those specified by this config item. Only the packages in the

65 + workspaces given will be published.

66 +

67 +The publish will fail if the package name and version combination already

68 +exists in the specified registry.

69 +

70 +Once a package is published with a given name and version, that specific

71 +name and version combination can never be used again, even if it is removed

72 +with [`npm unpublish`](/cli/v8/commands/npm-unpublish).

73 +

74 +As of `npm@5`, both a sha1sum and an integrity field with a sha512sum of the

75 +tarball will be submitted to the registry during publication. Subsequent

76 +installs will use the strongest supported algorithm to verify downloads.

77 +

78 +Similar to `--dry-run` see [`npm pack`](/cli/v8/commands/npm-pack), which figures

79 +out the files to be included and packs them into a tarball to be uploaded

80 +to the registry.

81 +

82 +### Files included in package

83 +

84 +To see what will be included in your package, run `npx npm-packlist`. All

85 +files are included by default, with the following exceptions:

86 +

87 +- Certain files that are relevant to package installation and distribution

88 + are always included. For example, `package.json`, `README.md`,

89 + `LICENSE`, and so on.

90 +

91 +- If there is a "files" list in

92 + [`package.json`](/cli/v8/configuring-npm/package-json), then only the files

93 + specified will be included. (If directories are specified, then they

94 + will be walked recursively and their contents included, subject to the

95 + same ignore rules.)

96 +

97 +- If there is a `.gitignore` or `.npmignore` file, then ignored files in

98 + that and all child directories will be excluded from the package. If

99 + _both_ files exist, then the `.gitignore` is ignored, and only the

100 + `.npmignore` is used.

101 +

102 + `.npmignore` files follow the [same pattern

103 + rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)

104 + as `.gitignore` files

105 +

106 +- If the file matches certain patterns, then it will _never_ be included,

107 + unless explicitly added to the `"files"` list in `package.json`, or

108 + un-ignored with a `!` rule in a `.npmignore` or `.gitignore` file.

109 +

110 +- Symbolic links are never included in npm packages.

111 +

112 +

113 +See [`developers`](/cli/v8/using-npm/developers) for full details on what's

114 +included in the published package, as well as details on how the package is

115 +built.

116 +

117 +### Configuration

118 +

119 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

120 +<!-- automatically generated, do not edit manually -->

121 +<!-- see lib/utils/config/definitions.js -->

122 +#### `tag`

123 +

124 +* Default: "latest"

125 +* Type: String

126 +

127 +If you ask npm to install a package and don't tell it a specific version,

128 +then it will install the specified tag.

129 +

130 +Also the tag that is added to the package@version specified by the `npm tag`

131 +command, if no explicit tag is given.

132 +

133 +When used by the `npm diff` command, this is the tag used to fetch the

134 +tarball that will be compared with the local files by default.

135 +

136 +<!-- automatically generated, do not edit manually -->

137 +<!-- see lib/utils/config/definitions.js -->

138 +

139 +#### `access`

140 +

141 +* Default: 'restricted' for scoped packages, 'public' for unscoped packages

142 +* Type: null, "restricted", or "public"

143 +

144 +When publishing scoped packages, the access level defaults to `restricted`.

145 +If you want your scoped package to be publicly viewable (and installable)

146 +set `--access=public`. The only valid values for `access` are `public` and

147 +`restricted`. Unscoped packages _always_ have an access level of `public`.

148 +

149 +Note: Using the `--access` flag on the `npm publish` command will only set

150 +the package access level on the initial publish of the package. Any

151 +subsequent `npm publish` commands using the `--access` flag will not have an

152 +effect to the access level. To make changes to the access level after the

153 +initial publish use `npm access`.

154 +

155 +<!-- automatically generated, do not edit manually -->

156 +<!-- see lib/utils/config/definitions.js -->

157 +

158 +#### `dry-run`

159 +

160 +* Default: false

161 +* Type: Boolean

162 +

163 +Indicates that you don't want npm to make any changes and that it should

164 +only report what it would have done. This can be passed into any of the

165 +commands that modify your local installation, eg, `install`, `update`,

166 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

167 +

168 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

169 +`owner`, etc.

170 +

171 +<!-- automatically generated, do not edit manually -->

172 +<!-- see lib/utils/config/definitions.js -->

173 +

174 +#### `otp`

175 +

176 +* Default: null

177 +* Type: null or String

178 +

179 +This is a one-time password from a two-factor authenticator. It's needed

180 +when publishing or changing package permissions with `npm access`.

181 +

182 +If not set, and a registry response fails with a challenge for a one-time

183 +password, npm will prompt on the command line for one.

184 +

185 +<!-- automatically generated, do not edit manually -->

186 +<!-- see lib/utils/config/definitions.js -->

187 +

188 +#### `workspace`

189 +

190 +* Default:

191 +* Type: String (can be set multiple times)

192 +

193 +Enable running a command in the context of the configured workspaces of the

194 +current project while filtering by running only the workspaces defined by

195 +this configuration option.

196 +

197 +Valid values for the `workspace` config are either:

198 +

199 +* Workspace names

200 +* Path to a workspace directory

201 +* Path to a parent workspace directory (will result in selecting all

202 + workspaces within that folder)

203 +

204 +When set for the `npm init` command, this may be set to the folder of a

205 +workspace which does not yet exist, to create the folder and set it up as a

206 +brand new workspace within the project.

207 +

208 +This value is not exported to the environment for child processes.

209 +

210 +<!-- automatically generated, do not edit manually -->

211 +<!-- see lib/utils/config/definitions.js -->

212 +

213 +#### `workspaces`

214 +

215 +* Default: null

216 +* Type: null or Boolean

217 +

218 +Set to true to run the command in the context of **all** configured

219 +workspaces.

220 +

221 +Explicitly setting this to false will cause commands like `install` to

222 +ignore workspaces altogether. When not set explicitly:

223 +

224 +- Commands that operate on the `node_modules` tree (install, update, etc.)

225 +will link workspaces into the `node_modules` folder. - Commands that do

226 +other things (test, exec, publish, etc.) will operate on the root project,

227 +_unless_ one or more workspaces are specified in the `workspace` config.

228 +

229 +This value is not exported to the environment for child processes.

230 +

231 +<!-- automatically generated, do not edit manually -->

232 +<!-- see lib/utils/config/definitions.js -->

233 +

234 +#### `include-workspace-root`

235 +

236 +* Default: false

237 +* Type: Boolean

238 +

239 +Include the workspace root when workspaces are enabled for a command.

240 +

241 +When false, specifying individual workspaces via the `workspace` config, or

242 +all workspaces via the `workspaces` flag, will cause npm to operate only on

243 +the specified workspaces, and not on the root project.

244 +

245 +<!-- automatically generated, do not edit manually -->

246 +<!-- see lib/utils/config/definitions.js -->

247 +

248 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

249 +

250 +### See Also

251 +

252 +* [npm-packlist package](http://npm.im/npm-packlist)

253 +* [npm registry](/cli/v8/using-npm/registry)

254 +* [npm scope](/cli/v8/using-npm/scope)

255 +* [npm adduser](/cli/v8/commands/npm-adduser)

256 +* [npm owner](/cli/v8/commands/npm-owner)

257 +* [npm deprecate](/cli/v8/commands/npm-deprecate)

258 +* [npm dist-tag](/cli/v8/commands/npm-dist-tag)

259 +* [npm pack](/cli/v8/commands/npm-pack)

260 +* [npm profile](/cli/v8/commands/npm-profile)

content/cli/v8/commands/npm-rebuild.md new

+153

@@ -0,0 +1,153 @@

1 +---

2 +title: npm-rebuild

3 +section: 1

4 +description: Rebuild a package

5 +redirect_from:

6 + - /cli/rebuild

7 + - /cli/rebuild.html

8 + - /cli/commands/rebuild

9 + - /cli-commands/rebuild

10 + - /cli-commands/rebuild.html

11 + - /cli-commands/npm-rebuild

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-rebuild.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm rebuild [[<@scope>/]<name>[@<version>] ...]

21 +

22 +alias: rb

23 +```

24 +

25 +### Description

26 +

27 +This command runs the `npm build` command on the matched folders. This is

28 +useful when you install a new version of node, and must recompile all your

29 +C++ addons with the new binary. It is also useful when installing with

30 +`--ignore-scripts` and `--no-bin-links`, to explicitly choose which

31 +packages to build and/or link bins.

32 +

33 +If one or more package names (and optionally version ranges) are provided,

34 +then only packages with a name and version matching one of the specifiers

35 +will be rebuilt.

36 +

37 +### Configuration

38 +

39 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

40 +<!-- automatically generated, do not edit manually -->

41 +<!-- see lib/utils/config/definitions.js -->

42 +#### `global`

43 +

44 +* Default: false

45 +* Type: Boolean

46 +

47 +Operates in "global" mode, so that packages are installed into the `prefix`

48 +folder instead of the current working directory. See

49 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

50 +

51 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

52 + of the current working directory.

53 +* bin files are linked to `{prefix}/bin`

54 +* man pages are linked to `{prefix}/share/man`

55 +

56 +<!-- automatically generated, do not edit manually -->

57 +<!-- see lib/utils/config/definitions.js -->

58 +

59 +#### `bin-links`

60 +

61 +* Default: true

62 +* Type: Boolean

63 +

64 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

65 +executables.

66 +

67 +Set to false to have it not do this. This can be used to work around the

68 +fact that some file systems don't support symlinks, even on ostensibly Unix

69 +systems.

70 +

71 +<!-- automatically generated, do not edit manually -->

72 +<!-- see lib/utils/config/definitions.js -->

73 +

74 +#### `ignore-scripts`

75 +

76 +* Default: false

77 +* Type: Boolean

78 +

79 +If true, npm does not run scripts specified in package.json files.

80 +

81 +Note that commands explicitly intended to run a particular script, such as

82 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

83 +will still run their intended script if `ignore-scripts` is set, but they

84 +will *not* run any pre- or post-scripts.

85 +

86 +<!-- automatically generated, do not edit manually -->

87 +<!-- see lib/utils/config/definitions.js -->

88 +

89 +#### `workspace`

90 +

91 +* Default:

92 +* Type: String (can be set multiple times)

93 +

94 +Enable running a command in the context of the configured workspaces of the

95 +current project while filtering by running only the workspaces defined by

96 +this configuration option.

97 +

98 +Valid values for the `workspace` config are either:

99 +

100 +* Workspace names

101 +* Path to a workspace directory

102 +* Path to a parent workspace directory (will result in selecting all

103 + workspaces within that folder)

104 +

105 +When set for the `npm init` command, this may be set to the folder of a

106 +workspace which does not yet exist, to create the folder and set it up as a

107 +brand new workspace within the project.

108 +

109 +This value is not exported to the environment for child processes.

110 +

111 +<!-- automatically generated, do not edit manually -->

112 +<!-- see lib/utils/config/definitions.js -->

113 +

114 +#### `workspaces`

115 +

116 +* Default: null

117 +* Type: null or Boolean

118 +

119 +Set to true to run the command in the context of **all** configured

120 +workspaces.

121 +

122 +Explicitly setting this to false will cause commands like `install` to

123 +ignore workspaces altogether. When not set explicitly:

124 +

125 +- Commands that operate on the `node_modules` tree (install, update, etc.)

126 +will link workspaces into the `node_modules` folder. - Commands that do

127 +other things (test, exec, publish, etc.) will operate on the root project,

128 +_unless_ one or more workspaces are specified in the `workspace` config.

129 +

130 +This value is not exported to the environment for child processes.

131 +

132 +<!-- automatically generated, do not edit manually -->

133 +<!-- see lib/utils/config/definitions.js -->

134 +

135 +#### `include-workspace-root`

136 +

137 +* Default: false

138 +* Type: Boolean

139 +

140 +Include the workspace root when workspaces are enabled for a command.

141 +

142 +When false, specifying individual workspaces via the `workspace` config, or

143 +all workspaces via the `workspaces` flag, will cause npm to operate only on

144 +the specified workspaces, and not on the root project.

145 +

146 +<!-- automatically generated, do not edit manually -->

147 +<!-- see lib/utils/config/definitions.js -->

148 +

149 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

150 +

151 +### See Also

152 +

153 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/commands/npm-repo.md new

+115

@@ -0,0 +1,115 @@

1 +---

2 +title: npm-repo

3 +section: 1

4 +description: Open package repository page in the browser

5 +redirect_from:

6 + - /cli/repo

7 + - /cli/repo.html

8 + - /cli/commands/repo

9 + - /cli-commands/repo

10 + - /cli-commands/repo.html

11 + - /cli-commands/npm-repo

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-repo.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm repo [<pkgname> [<pkgname> ...]]

21 +```

22 +

23 +### Description

24 +

25 +This command tries to guess at the likely location of a package's

26 +repository URL, and then tries to open it using the `--browser` config

27 +param. If no package name is provided, it will search for a `package.json`

28 +in the current folder and use the `repository` property.

29 +

30 +### Configuration

31 +

32 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

33 +<!-- automatically generated, do not edit manually -->

34 +<!-- see lib/utils/config/definitions.js -->

35 +#### `browser`

36 +

37 +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`

38 +* Type: null, Boolean, or String

39 +

40 +The browser that is called by npm commands to open websites.

41 +

42 +Set to `false` to suppress browser behavior and instead print urls to

43 +terminal.

44 +

45 +Set to `true` to use default system URL opener.

46 +

47 +<!-- automatically generated, do not edit manually -->

48 +<!-- see lib/utils/config/definitions.js -->

49 +

50 +#### `workspace`

51 +

52 +* Default:

53 +* Type: String (can be set multiple times)

54 +

55 +Enable running a command in the context of the configured workspaces of the

56 +current project while filtering by running only the workspaces defined by

57 +this configuration option.

58 +

59 +Valid values for the `workspace` config are either:

60 +

61 +* Workspace names

62 +* Path to a workspace directory

63 +* Path to a parent workspace directory (will result in selecting all

64 + workspaces within that folder)

65 +

66 +When set for the `npm init` command, this may be set to the folder of a

67 +workspace which does not yet exist, to create the folder and set it up as a

68 +brand new workspace within the project.

69 +

70 +This value is not exported to the environment for child processes.

71 +

72 +<!-- automatically generated, do not edit manually -->

73 +<!-- see lib/utils/config/definitions.js -->

74 +

75 +#### `workspaces`

76 +

77 +* Default: null

78 +* Type: null or Boolean

79 +

80 +Set to true to run the command in the context of **all** configured

81 +workspaces.

82 +

83 +Explicitly setting this to false will cause commands like `install` to

84 +ignore workspaces altogether. When not set explicitly:

85 +

86 +- Commands that operate on the `node_modules` tree (install, update, etc.)

87 +will link workspaces into the `node_modules` folder. - Commands that do

88 +other things (test, exec, publish, etc.) will operate on the root project,

89 +_unless_ one or more workspaces are specified in the `workspace` config.

90 +

91 +This value is not exported to the environment for child processes.

92 +

93 +<!-- automatically generated, do not edit manually -->

94 +<!-- see lib/utils/config/definitions.js -->

95 +

96 +#### `include-workspace-root`

97 +

98 +* Default: false

99 +* Type: Boolean

100 +

101 +Include the workspace root when workspaces are enabled for a command.

102 +

103 +When false, specifying individual workspaces via the `workspace` config, or

104 +all workspaces via the `workspaces` flag, will cause npm to operate only on

105 +the specified workspaces, and not on the root project.

106 +

107 +<!-- automatically generated, do not edit manually -->

108 +<!-- see lib/utils/config/definitions.js -->

109 +

110 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

111 +

112 +### See Also

113 +

114 +* [npm docs](/cli/v8/commands/npm-docs)

115 +* [npm config](/cli/v8/commands/npm-config)

content/cli/v8/commands/npm-restart.md new

+87

@@ -0,0 +1,87 @@

1 +---

2 +title: npm-restart

3 +section: 1

4 +description: Restart a package

5 +redirect_from:

6 + - /cli/restart

7 + - /cli/restart.html

8 + - /cli/commands/restart

9 + - /cli-commands/restart

10 + - /cli-commands/restart.html

11 + - /cli-commands/npm-restart

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-restart.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm restart [-- <args>]

21 +```

22 +

23 +### Description

24 +

25 +This restarts a project. It is equivalent to running `npm run-script

26 +restart`.

27 +

28 +If the current project has a `"restart"` script specified in

29 +`package.json`, then the following scripts will be run:

30 +

31 +1. prerestart

32 +2. restart

33 +3. postrestart

34 +

35 +If it does _not_ have a `"restart"` script specified, but it does have

36 +`stop` and/or `start` scripts, then the following scripts will be run:

37 +

38 +1. prerestart

39 +2. prestop

40 +3. stop

41 +4. poststop

42 +6. prestart

43 +7. start

44 +8. poststart

45 +9. postrestart

46 +

47 +### Configuration

48 +

49 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

50 +<!-- automatically generated, do not edit manually -->

51 +<!-- see lib/utils/config/definitions.js -->

52 +#### `ignore-scripts`

53 +

54 +* Default: false

55 +* Type: Boolean

56 +

57 +If true, npm does not run scripts specified in package.json files.

58 +

59 +Note that commands explicitly intended to run a particular script, such as

60 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

61 +will still run their intended script if `ignore-scripts` is set, but they

62 +will *not* run any pre- or post-scripts.

63 +

64 +<!-- automatically generated, do not edit manually -->

65 +<!-- see lib/utils/config/definitions.js -->

66 +

67 +#### `script-shell`

68 +

69 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

70 +* Type: null or String

71 +

72 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

73 +init <pkg>` commands.

74 +

75 +<!-- automatically generated, do not edit manually -->

76 +<!-- see lib/utils/config/definitions.js -->

77 +

78 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

79 +

80 +### See Also

81 +

82 +* [npm run-script](/cli/v8/commands/npm-run-script)

83 +* [npm scripts](/cli/v8/using-npm/scripts)

84 +* [npm test](/cli/v8/commands/npm-test)

85 +* [npm start](/cli/v8/commands/npm-start)

86 +* [npm stop](/cli/v8/commands/npm-stop)

87 +* [npm restart](/cli/v8/commands/npm-restart)

content/cli/v8/commands/npm-root.md new

+66

@@ -0,0 +1,66 @@

1 +---

2 +title: npm-root

3 +section: 1

4 +description: Display npm root

5 +redirect_from:

6 + - /cli/root

7 + - /cli/root.html

8 + - /cli/commands/root

9 + - /cli-commands/root

10 + - /cli-commands/root.html

11 + - /cli-commands/npm-root

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-root.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm root [-g]

21 +```

22 +

23 +### Description

24 +

25 +Print the effective `node_modules` folder to standard out.

26 +

27 +Useful for using npm in shell scripts that do things with the

28 +`node_modules` folder. For example:

29 +

30 +```bash

31 +#!/bin/bash

32 +global_node_modules="$(npm root --global)"

33 +echo "Global packages installed in: ${global_node_modules}"

34 +```

35 +

36 +### Configuration

37 +

38 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

39 +<!-- automatically generated, do not edit manually -->

40 +<!-- see lib/utils/config/definitions.js -->

41 +#### `global`

42 +

43 +* Default: false

44 +* Type: Boolean

45 +

46 +Operates in "global" mode, so that packages are installed into the `prefix`

47 +folder instead of the current working directory. See

48 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

49 +

50 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

51 + of the current working directory.

52 +* bin files are linked to `{prefix}/bin`

53 +* man pages are linked to `{prefix}/share/man`

54 +

55 +<!-- automatically generated, do not edit manually -->

56 +<!-- see lib/utils/config/definitions.js -->

57 +

58 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

59 +

60 +### See Also

61 +

62 +* [npm prefix](/cli/v8/commands/npm-prefix)

63 +* [npm bin](/cli/v8/commands/npm-bin)

64 +* [npm folders](/cli/v8/configuring-npm/folders)

65 +* [npm config](/cli/v8/commands/npm-config)

66 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-run-script.md new

+263

@@ -0,0 +1,263 @@

1 +---

2 +title: npm-run-script

3 +section: 1

4 +description: Run arbitrary package scripts

5 +redirect_from:

6 + - /cli/run-script

7 + - /cli/run-script.html

8 + - /cli/commands/run-script

9 + - /cli-commands/run-script

10 + - /cli-commands/run-script.html

11 + - /cli-commands/npm-run-script

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-run-script.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm run-script <command> [--if-present] [--silent] [-- <args>]

21 +npm run-script <command> [--workspace=<workspace-name>]

22 +npm run-script <command> [--workspaces]

23 +

24 +aliases: run, rum, urn

25 +```

26 +

27 +### Description

28 +

29 +This runs an arbitrary command from a package's `"scripts"` object. If no

30 +`"command"` is provided, it will list the available scripts.

31 +

32 +`run[-script]` is used by the test, start, restart, and stop commands, but

33 +can be called directly, as well. When the scripts in the package are

34 +printed out, they're separated into lifecycle (test, start, restart) and

35 +directly-run scripts.

36 +

37 +Any positional arguments are passed to the specified script. Use `--` to

38 +pass `-`-prefixed flags and options which would otherwise be parsed by npm.

39 +

40 +For example:

41 +

42 +```bash

43 +npm run test -- --grep="pattern"

44 +```

45 +

46 +The arguments will only be passed to the script specified after `npm run`

47 +and not to any `pre` or `post` script.

48 +

49 +The `env` script is a special built-in command that can be used to list

50 +environment variables that will be available to the script at runtime. If an

51 +"env" command is defined in your package, it will take precedence over the

52 +built-in.

53 +

54 +In addition to the shell's pre-existing `PATH`, `npm run` adds

55 +`node_modules/.bin` to the `PATH` provided to scripts. Any binaries

56 +provided by locally-installed dependencies can be used without the

57 +`node_modules/.bin` prefix. For example, if there is a `devDependency` on

58 +`tap` in your package, you should write:

59 +

60 +```bash

61 +"scripts": {"test": "tap test/*.js"}

62 +```

63 +

64 +instead of

65 +

66 +```bash

67 +"scripts": {"test": "node_modules/.bin/tap test/*.js"}

68 +```

69 +

70 +The actual shell your script is run within is platform dependent. By default,

71 +on Unix-like systems it is the `/bin/sh` command, on Windows it is

72 +`cmd.exe`.

73 +The actual shell referred to by `/bin/sh` also depends on the system.

74 +You can customize the shell with the `script-shell` configuration.

75 +

76 +Scripts are run from the root of the package folder, regardless of what the

77 +current working directory is when `npm run` is called. If you want your

78 +script to use different behavior based on what subdirectory you're in, you

79 +can use the `INIT_CWD` environment variable, which holds the full path you

80 +were in when you ran `npm run`.

81 +

82 +`npm run` sets the `NODE` environment variable to the `node` executable

83 +with which `npm` is executed.

84 +

85 +If you try to run a script without having a `node_modules` directory and it

86 +fails, you will be given a warning to run `npm install`, just in case you've

87 +forgotten.

88 +

89 +### Workspaces support

90 +

91 +You may use the `workspace` or `workspaces` configs in order to run an

92 +arbitrary command from a package's `"scripts"` object in the context of the

93 +specified workspaces. If no `"command"` is provided, it will list the available

94 +scripts for each of these configured workspaces.

95 +

96 +Given a project with configured workspaces, e.g:

97 +

98 +```

99 +.

100 ++-- package.json

101 +`-- packages

102 + +-- a

103 + | `-- package.json

104 + +-- b

105 + | `-- package.json

106 + `-- c

107 + `-- package.json

108 +```

109 +

110 +Assuming the workspace configuration is properly set up at the root level

111 +`package.json` file. e.g:

112 +

113 +```

114 +{

115 + "workspaces": [ "./packages/*" ]

116 +}

117 +```

118 +

119 +And that each of the configured workspaces has a configured `test` script,

120 +we can run tests in all of them using the `workspaces` config:

121 +

122 +```

123 +npm test --workspaces

124 +```

125 +

126 +#### Filtering workspaces

127 +

128 +It's also possible to run a script in a single workspace using the `workspace`

129 +config along with a name or directory path:

130 +

131 +```

132 +npm test --workspace=a

133 +```

134 +

135 +The `workspace` config can also be specified multiple times in order to run a

136 +specific script in the context of multiple workspaces. When defining values for

137 +the `workspace` config in the command line, it also possible to use `-w` as a

138 +shorthand, e.g:

139 +

140 +```

141 +npm test -w a -w b

142 +```

143 +

144 +This last command will run `test` in both `./packages/a` and `./packages/b`

145 +packages.

146 +

147 +### Configuration

148 +

149 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

150 +<!-- automatically generated, do not edit manually -->

151 +<!-- see lib/utils/config/definitions.js -->

152 +#### `workspace`

153 +

154 +* Default:

155 +* Type: String (can be set multiple times)

156 +

157 +Enable running a command in the context of the configured workspaces of the

158 +current project while filtering by running only the workspaces defined by

159 +this configuration option.

160 +

161 +Valid values for the `workspace` config are either:

162 +

163 +* Workspace names

164 +* Path to a workspace directory

165 +* Path to a parent workspace directory (will result in selecting all

166 + workspaces within that folder)

167 +

168 +When set for the `npm init` command, this may be set to the folder of a

169 +workspace which does not yet exist, to create the folder and set it up as a

170 +brand new workspace within the project.

171 +

172 +This value is not exported to the environment for child processes.

173 +

174 +<!-- automatically generated, do not edit manually -->

175 +<!-- see lib/utils/config/definitions.js -->

176 +

177 +#### `workspaces`

178 +

179 +* Default: null

180 +* Type: null or Boolean

181 +

182 +Set to true to run the command in the context of **all** configured

183 +workspaces.

184 +

185 +Explicitly setting this to false will cause commands like `install` to

186 +ignore workspaces altogether. When not set explicitly:

187 +

188 +- Commands that operate on the `node_modules` tree (install, update, etc.)

189 +will link workspaces into the `node_modules` folder. - Commands that do

190 +other things (test, exec, publish, etc.) will operate on the root project,

191 +_unless_ one or more workspaces are specified in the `workspace` config.

192 +

193 +This value is not exported to the environment for child processes.

194 +

195 +<!-- automatically generated, do not edit manually -->

196 +<!-- see lib/utils/config/definitions.js -->

197 +

198 +#### `include-workspace-root`

199 +

200 +* Default: false

201 +* Type: Boolean

202 +

203 +Include the workspace root when workspaces are enabled for a command.

204 +

205 +When false, specifying individual workspaces via the `workspace` config, or

206 +all workspaces via the `workspaces` flag, will cause npm to operate only on

207 +the specified workspaces, and not on the root project.

208 +

209 +<!-- automatically generated, do not edit manually -->

210 +<!-- see lib/utils/config/definitions.js -->

211 +

212 +#### `if-present`

213 +

214 +* Default: false

215 +* Type: Boolean

216 +

217 +If true, npm will not exit with an error code when `run-script` is invoked

218 +for a script that isn't defined in the `scripts` section of `package.json`.

219 +This option can be used when it's desirable to optionally run a script when

220 +it's present and fail if the script fails. This is useful, for example, when

221 +running scripts that may only apply for some builds in an otherwise generic

222 +CI setup.

223 +

224 +<!-- automatically generated, do not edit manually -->

225 +<!-- see lib/utils/config/definitions.js -->

226 +

227 +#### `ignore-scripts`

228 +

229 +* Default: false

230 +* Type: Boolean

231 +

232 +If true, npm does not run scripts specified in package.json files.

233 +

234 +Note that commands explicitly intended to run a particular script, such as

235 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

236 +will still run their intended script if `ignore-scripts` is set, but they

237 +will *not* run any pre- or post-scripts.

238 +

239 +<!-- automatically generated, do not edit manually -->

240 +<!-- see lib/utils/config/definitions.js -->

241 +

242 +#### `script-shell`

243 +

244 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

245 +* Type: null or String

246 +

247 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

248 +init <pkg>` commands.

249 +

250 +<!-- automatically generated, do not edit manually -->

251 +<!-- see lib/utils/config/definitions.js -->

252 +

253 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

254 +

255 +### See Also

256 +

257 +* [npm scripts](/cli/v8/using-npm/scripts)

258 +* [npm test](/cli/v8/commands/npm-test)

259 +* [npm start](/cli/v8/commands/npm-start)

260 +* [npm restart](/cli/v8/commands/npm-restart)

261 +* [npm stop](/cli/v8/commands/npm-stop)

262 +* [npm config](/cli/v8/commands/npm-config)

263 +* [npm workspaces](/cli/v8/using-npm/workspaces)

content/cli/v8/commands/npm-search.md new

+185

@@ -0,0 +1,185 @@

1 +---

2 +title: npm-search

3 +section: 1

4 +description: Search for packages

5 +redirect_from:

6 + - /cli/search

7 + - /cli/search.html

8 + - /cli/commands/search

9 + - /cli-commands/search

10 + - /cli-commands/search.html

11 + - /cli-commands/npm-search

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-search.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm search [-l|--long] [--json] [--parseable] [--no-description] [search terms ...]

21 +

22 +aliases: s, se, find

23 +```

24 +

25 +Note: This command is unaware of workspaces.

26 +

27 +### Description

28 +

29 +Search the registry for packages matching the search terms. `npm search`

30 +performs a linear, incremental, lexically-ordered search through package

31 +metadata for all files in the registry. If your terminal has color

32 +support, it will further highlight the matches in the results. This can

33 +be disabled with the config item `color`

34 +

35 +Additionally, using the `--searchopts` and `--searchexclude` options

36 +paired with more search terms will include and exclude further patterns.

37 +The main difference between `--searchopts` and the standard search terms

38 +is that the former does not highlight results in the output and you can

39 +use them more fine-grained filtering. Additionally, you can add both of

40 +these to your config to change default search filtering behavior.

41 +

42 +Search also allows targeting of maintainers in search results, by prefixing

43 +their npm username with `=`.

44 +

45 +If a term starts with `/`, then it's interpreted as a regular expression

46 +and supports standard JavaScript RegExp syntax. In this case search will

47 +ignore a trailing `/` . (Note you must escape or quote many regular

48 +expression characters in most shells.)

49 +

50 +### Configuration

51 +

52 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

53 +<!-- automatically generated, do not edit manually -->

54 +<!-- see lib/utils/config/definitions.js -->

55 +#### `long`

56 +

57 +* Default: false

58 +* Type: Boolean

59 +

60 +Show extended information in `ls`, `search`, and `help-search`.

61 +

62 +<!-- automatically generated, do not edit manually -->

63 +<!-- see lib/utils/config/definitions.js -->

64 +

65 +#### `json`

66 +

67 +* Default: false

68 +* Type: Boolean

69 +

70 +Whether or not to output JSON data, rather than the normal output.

71 +

72 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

73 + saving them to your `package.json`.

74 +

75 +Not supported by all npm commands.

76 +

77 +<!-- automatically generated, do not edit manually -->

78 +<!-- see lib/utils/config/definitions.js -->

79 +

80 +#### `color`

81 +

82 +* Default: true unless the NO_COLOR environ is set to something other than '0'

83 +* Type: "always" or Boolean

84 +

85 +If false, never shows colors. If `"always"` then always shows colors. If

86 +true, then only prints color codes for tty file descriptors.

87 +

88 +<!-- automatically generated, do not edit manually -->

89 +<!-- see lib/utils/config/definitions.js -->

90 +

91 +#### `parseable`

92 +

93 +* Default: false

94 +* Type: Boolean

95 +

96 +Output parseable results from commands that write to standard output. For

97 +`npm search`, this will be tab-separated table format.

98 +

99 +<!-- automatically generated, do not edit manually -->

100 +<!-- see lib/utils/config/definitions.js -->

101 +

102 +#### `description`

103 +

104 +* Default: true

105 +* Type: Boolean

106 +

107 +Show the description in `npm search`

108 +

109 +<!-- automatically generated, do not edit manually -->

110 +<!-- see lib/utils/config/definitions.js -->

111 +

112 +#### `searchopts`

113 +

114 +* Default: ""

115 +* Type: String

116 +

117 +Space-separated options that are always passed to search.

118 +

119 +<!-- automatically generated, do not edit manually -->

120 +<!-- see lib/utils/config/definitions.js -->

121 +

122 +#### `searchexclude`

123 +

124 +* Default: ""

125 +* Type: String

126 +

127 +Space-separated options that limit the results from search.

128 +

129 +<!-- automatically generated, do not edit manually -->

130 +<!-- see lib/utils/config/definitions.js -->

131 +

132 +#### `registry`

133 +

134 +* Default: "https://registry.npmjs.org/"

135 +* Type: URL

136 +

137 +The base URL of the npm registry.

138 +

139 +<!-- automatically generated, do not edit manually -->

140 +<!-- see lib/utils/config/definitions.js -->

141 +

142 +#### `prefer-online`

143 +

144 +* Default: false

145 +* Type: Boolean

146 +

147 +If true, staleness checks for cached data will be forced, making the CLI

148 +look for updates immediately even for fresh package data.

149 +

150 +<!-- automatically generated, do not edit manually -->

151 +<!-- see lib/utils/config/definitions.js -->

152 +

153 +#### `prefer-offline`

154 +

155 +* Default: false

156 +* Type: Boolean

157 +

158 +If true, staleness checks for cached data will be bypassed, but missing data

159 +will be requested from the server. To force full offline mode, use

160 +`--offline`.

161 +

162 +<!-- automatically generated, do not edit manually -->

163 +<!-- see lib/utils/config/definitions.js -->

164 +

165 +#### `offline`

166 +

167 +* Default: false

168 +* Type: Boolean

169 +

170 +Force offline mode: no network requests will be done during install. To

171 +allow the CLI to fill in missing cache data, see `--prefer-offline`.

172 +

173 +<!-- automatically generated, do not edit manually -->

174 +<!-- see lib/utils/config/definitions.js -->

175 +

176 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

177 +

178 +### See Also

179 +

180 +* [npm registry](/cli/v8/using-npm/registry)

181 +* [npm config](/cli/v8/commands/npm-config)

182 +* [npmrc](/cli/v8/configuring-npm/npmrc)

183 +* [npm view](/cli/v8/commands/npm-view)

184 +* [npm cache](/cli/v8/commands/npm-cache)

185 +* https://npm.im/npm-registry-fetch

content/cli/v8/commands/npm-set-script.md new

+111

@@ -0,0 +1,111 @@

1 +---

2 +title: npm-set-script

3 +section: 1

4 +description: Set tasks in the scripts section of package.json

5 +redirect_from:

6 + - /cli/set-script

7 + - /cli/set-script.html

8 + - /cli/commands/set-script

9 + - /cli-commands/set-script

10 + - /cli-commands/set-script.html

11 + - /cli-commands/npm-set-script

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-set-script.md

15 +---

16 +

17 +### Synopsis

18 +An npm command that lets you create a task in the `scripts` section of the `package.json`.

19 +

20 +```bash

21 +npm set-script [<script>] [<command>]

22 +```

23 +

24 +

25 +**Example:**

26 +

27 +* `npm set-script start "http-server ."`

28 +

29 +```json

30 +{

31 + "name": "my-project",

32 + "scripts": {

33 + "start": "http-server .",

34 + "test": "some existing value"

35 + }

36 +}

37 +```

38 +

39 +### Configuration

40 +

41 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

42 +<!-- automatically generated, do not edit manually -->

43 +<!-- see lib/utils/config/definitions.js -->

44 +#### `workspace`

45 +

46 +* Default:

47 +* Type: String (can be set multiple times)

48 +

49 +Enable running a command in the context of the configured workspaces of the

50 +current project while filtering by running only the workspaces defined by

51 +this configuration option.

52 +

53 +Valid values for the `workspace` config are either:

54 +

55 +* Workspace names

56 +* Path to a workspace directory

57 +* Path to a parent workspace directory (will result in selecting all

58 + workspaces within that folder)

59 +

60 +When set for the `npm init` command, this may be set to the folder of a

61 +workspace which does not yet exist, to create the folder and set it up as a

62 +brand new workspace within the project.

63 +

64 +This value is not exported to the environment for child processes.

65 +

66 +<!-- automatically generated, do not edit manually -->

67 +<!-- see lib/utils/config/definitions.js -->

68 +

69 +#### `workspaces`

70 +

71 +* Default: null

72 +* Type: null or Boolean

73 +

74 +Set to true to run the command in the context of **all** configured

75 +workspaces.

76 +

77 +Explicitly setting this to false will cause commands like `install` to

78 +ignore workspaces altogether. When not set explicitly:

79 +

80 +- Commands that operate on the `node_modules` tree (install, update, etc.)

81 +will link workspaces into the `node_modules` folder. - Commands that do

82 +other things (test, exec, publish, etc.) will operate on the root project,

83 +_unless_ one or more workspaces are specified in the `workspace` config.

84 +

85 +This value is not exported to the environment for child processes.

86 +

87 +<!-- automatically generated, do not edit manually -->

88 +<!-- see lib/utils/config/definitions.js -->

89 +

90 +#### `include-workspace-root`

91 +

92 +* Default: false

93 +* Type: Boolean

94 +

95 +Include the workspace root when workspaces are enabled for a command.

96 +

97 +When false, specifying individual workspaces via the `workspace` config, or

98 +all workspaces via the `workspaces` flag, will cause npm to operate only on

99 +the specified workspaces, and not on the root project.

100 +

101 +<!-- automatically generated, do not edit manually -->

102 +<!-- see lib/utils/config/definitions.js -->

103 +

104 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

105 +

106 +### See Also

107 +

108 +* [npm run-script](/cli/v8/commands/npm-run-script)

109 +* [npm install](/cli/v8/commands/npm-install)

110 +* [npm test](/cli/v8/commands/npm-test)

111 +* [npm start](/cli/v8/commands/npm-start)

content/cli/v8/commands/npm-shrinkwrap.md new

+42

@@ -0,0 +1,42 @@

1 +---

2 +title: npm-shrinkwrap

3 +section: 1

4 +description: Lock down dependency versions for publication

5 +redirect_from:

6 + - /cli/shrinkwrap

7 + - /cli/shrinkwrap.html

8 + - /cli/commands/shrinkwrap

9 + - /cli-commands/shrinkwrap

10 + - /cli-commands/shrinkwrap.html

11 + - /cli-commands/npm-shrinkwrap

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-shrinkwrap.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm shrinkwrap

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +This command repurposes `package-lock.json` into a publishable

28 +`npm-shrinkwrap.json` or simply creates a new one. The file created and

29 +updated by this command will then take precedence over any other existing

30 +or future `package-lock.json` files. For a detailed explanation of the

31 +design and purpose of package locks in npm, see

32 +[package-lock-json](/cli/v8/configuring-npm/package-lock-json).

33 +

34 +### See Also

35 +

36 +* [npm install](/cli/v8/commands/npm-install)

37 +* [npm run-script](/cli/v8/commands/npm-run-script)

38 +* [npm scripts](/cli/v8/using-npm/scripts)

39 +* [package.json](/cli/v8/configuring-npm/package-json)

40 +* [package-lock.json](/cli/v8/configuring-npm/package-lock-json)

41 +* [npm-shrinkwrap.json](/cli/v8/configuring-npm/npm-shrinkwrap-json)

42 +* [npm ls](/cli/v8/commands/npm-ls)

content/cli/v8/commands/npm-star.md new

+81

@@ -0,0 +1,81 @@

1 +---

2 +title: npm-star

3 +section: 1

4 +description: Mark your favorite packages

5 +redirect_from:

6 + - /cli/star

7 + - /cli/star.html

8 + - /cli/commands/star

9 + - /cli-commands/star

10 + - /cli-commands/star.html

11 + - /cli-commands/npm-star

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-star.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm star [<pkg>...]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +"Starring" a package means that you have some interest in it. It's

28 +a vaguely positive way to show that you care.

29 +

30 +It's a boolean thing. Starring repeatedly has no additional effect.

31 +

32 +### More

33 +

34 +There's also these extra commands to help you manage your favorite packages:

35 +

36 +#### Unstar

37 +

38 +You can also "unstar" a package using [`npm unstar`](/cli/v8/commands/npm-unstar)

39 +

40 +"Unstarring" is the same thing, but in reverse.

41 +

42 +#### Listing stars

43 +

44 +You can see all your starred packages using [`npm stars`](/cli/v8/commands/npm-stars)

45 +

46 +### Configuration

47 +

48 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

49 +<!-- automatically generated, do not edit manually -->

50 +<!-- see lib/utils/config/definitions.js -->

51 +#### `registry`

52 +

53 +* Default: "https://registry.npmjs.org/"

54 +* Type: URL

55 +

56 +The base URL of the npm registry.

57 +

58 +<!-- automatically generated, do not edit manually -->

59 +<!-- see lib/utils/config/definitions.js -->

60 +

61 +#### `unicode`

62 +

63 +* Default: false on windows, true on mac/unix systems with a unicode locale,

64 + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables.

65 +* Type: Boolean

66 +

67 +When set to true, npm uses unicode characters in the tree output. When

68 +false, it uses ascii characters instead of unicode glyphs.

69 +

70 +<!-- automatically generated, do not edit manually -->

71 +<!-- see lib/utils/config/definitions.js -->

72 +

73 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

74 +

75 +### See Also

76 +

77 +* [npm unstar](/cli/v8/commands/npm-unstar)

78 +* [npm stars](/cli/v8/commands/npm-stars)

79 +* [npm view](/cli/v8/commands/npm-view)

80 +* [npm whoami](/cli/v8/commands/npm-whoami)

81 +* [npm adduser](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm-stars.md new

+55

@@ -0,0 +1,55 @@

1 +---

2 +title: npm-stars

3 +section: 1

4 +description: View packages marked as favorites

5 +redirect_from:

6 + - /cli/stars

7 + - /cli/stars.html

8 + - /cli/commands/stars

9 + - /cli-commands/stars

10 + - /cli-commands/stars.html

11 + - /cli-commands/npm-stars

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-stars.md

15 +---

16 +

17 +### Synopsis

18 +```bash

19 +npm stars [<user>]

20 +```

21 +

22 +Note: This command is unaware of workspaces.

23 +

24 +### Description

25 +

26 +If you have starred a lot of neat things and want to find them again

27 +quickly this command lets you do just that.

28 +

29 +You may also want to see your friend's favorite packages, in this case

30 +you will most certainly enjoy this command.

31 +

32 +### Configuration

33 +

34 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

35 +<!-- automatically generated, do not edit manually -->

36 +<!-- see lib/utils/config/definitions.js -->

37 +#### `registry`

38 +

39 +* Default: "https://registry.npmjs.org/"

40 +* Type: URL

41 +

42 +The base URL of the npm registry.

43 +

44 +<!-- automatically generated, do not edit manually -->

45 +<!-- see lib/utils/config/definitions.js -->

46 +

47 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

48 +

49 +### See Also

50 +

51 +* [npm star](/cli/v8/commands/npm-star)

52 +* [npm unstar](/cli/v8/commands/npm-unstar)

53 +* [npm view](/cli/v8/commands/npm-view)

54 +* [npm whoami](/cli/v8/commands/npm-whoami)

55 +* [npm adduser](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm-start.md new

+97

@@ -0,0 +1,97 @@

1 +---

2 +title: npm-start

3 +section: 1

4 +description: Start a package

5 +redirect_from:

6 + - /cli/start

7 + - /cli/start.html

8 + - /cli/commands/start

9 + - /cli-commands/start

10 + - /cli-commands/start.html

11 + - /cli-commands/npm-start

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-start.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm start [-- <args>]

21 +```

22 +

23 +### Description

24 +

25 +This runs a predefined command specified in the `"start"` property of

26 +a package's `"scripts"` object.

27 +

28 +If the `"scripts"` object does not define a `"start"` property, npm

29 +will run `node server.js`.

30 +

31 +Note that this is different from the default node behavior of running

32 +the file specified in a package's `"main"` attribute when evoking with

33 +`node .`

34 +

35 +As of [`npm@2.0.0`](https://blog.npmjs.org/post/98131109725/npm-2-0-0), you can

36 +use custom arguments when executing scripts. Refer to [`npm run-script`](/cli/v8/commands/npm-run-script) for more details.

37 +

38 +### Example

39 +

40 +```json

41 +{

42 + "scripts": {

43 + "start": "node foo.js"

44 + }

45 +}

46 +```

47 +

48 +```bash

49 +npm start

50 +

51 +> npm@x.x.x start

52 +> node foo.js

53 +

54 +(foo.js output would be here)

55 +

56 +```

57 +

58 +### Configuration

59 +

60 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

61 +<!-- automatically generated, do not edit manually -->

62 +<!-- see lib/utils/config/definitions.js -->

63 +#### `ignore-scripts`

64 +

65 +* Default: false

66 +* Type: Boolean

67 +

68 +If true, npm does not run scripts specified in package.json files.

69 +

70 +Note that commands explicitly intended to run a particular script, such as

71 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

72 +will still run their intended script if `ignore-scripts` is set, but they

73 +will *not* run any pre- or post-scripts.

74 +

75 +<!-- automatically generated, do not edit manually -->

76 +<!-- see lib/utils/config/definitions.js -->

77 +

78 +#### `script-shell`

79 +

80 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

81 +* Type: null or String

82 +

83 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

84 +init <pkg>` commands.

85 +

86 +<!-- automatically generated, do not edit manually -->

87 +<!-- see lib/utils/config/definitions.js -->

88 +

89 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

90 +

91 +### See Also

92 +

93 +* [npm run-script](/cli/v8/commands/npm-run-script)

94 +* [npm scripts](/cli/v8/using-npm/scripts)

95 +* [npm test](/cli/v8/commands/npm-test)

96 +* [npm restart](/cli/v8/commands/npm-restart)

97 +* [npm stop](/cli/v8/commands/npm-stop)

content/cli/v8/commands/npm-stop.md new

+90

@@ -0,0 +1,90 @@

1 +---

2 +title: npm-stop

3 +section: 1

4 +description: Stop a package

5 +redirect_from:

6 + - /cli/stop

7 + - /cli/stop.html

8 + - /cli/commands/stop

9 + - /cli-commands/stop

10 + - /cli-commands/stop.html

11 + - /cli-commands/npm-stop

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-stop.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm stop [-- <args>]

21 +```

22 +

23 +### Description

24 +

25 +This runs a predefined command specified in the "stop" property of a

26 +package's "scripts" object.

27 +

28 +Unlike with [npm start](/cli/v8/commands/npm-start), there is no default script

29 +that will run if the `"stop"` property is not defined.

30 +

31 +### Example

32 +

33 +```json

34 +{

35 + "scripts": {

36 + "stop": "node bar.js"

37 + }

38 +}

39 +```

40 +

41 +```bash

42 +npm stop

43 +

44 +> npm@x.x.x stop

45 +> node bar.js

46 +

47 +(bar.js output would be here)

48 +

49 +```

50 +

51 +### Configuration

52 +

53 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

54 +<!-- automatically generated, do not edit manually -->

55 +<!-- see lib/utils/config/definitions.js -->

56 +#### `ignore-scripts`

57 +

58 +* Default: false

59 +* Type: Boolean

60 +

61 +If true, npm does not run scripts specified in package.json files.

62 +

63 +Note that commands explicitly intended to run a particular script, such as

64 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

65 +will still run their intended script if `ignore-scripts` is set, but they

66 +will *not* run any pre- or post-scripts.

67 +

68 +<!-- automatically generated, do not edit manually -->

69 +<!-- see lib/utils/config/definitions.js -->

70 +

71 +#### `script-shell`

72 +

73 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

74 +* Type: null or String

75 +

76 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

77 +init <pkg>` commands.

78 +

79 +<!-- automatically generated, do not edit manually -->

80 +<!-- see lib/utils/config/definitions.js -->

81 +

82 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

83 +

84 +### See Also

85 +

86 +* [npm run-script](/cli/v8/commands/npm-run-script)

87 +* [npm scripts](/cli/v8/using-npm/scripts)

88 +* [npm test](/cli/v8/commands/npm-test)

89 +* [npm start](/cli/v8/commands/npm-start)

90 +* [npm restart](/cli/v8/commands/npm-restart)

content/cli/v8/commands/npm-team.md new

+175

@@ -0,0 +1,175 @@

1 +---

2 +title: npm-team

3 +section: 1

4 +description: Manage organization teams and team memberships

5 +redirect_from:

6 + - /cli/team

7 + - /cli/team.html

8 + - /cli/commands/team

9 + - /cli-commands/team

10 + - /cli-commands/team.html

11 + - /cli-commands/npm-team

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-team.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm team create <scope:team>

21 +npm team destroy <scope:team>

22 +

23 +npm team add <scope:team> <user>

24 +npm team rm <scope:team> <user>

25 +

26 +npm team ls <scope>|<scope:team>

27 +```

28 +

29 +Note: This command is unaware of workspaces.

30 +

31 +### Description

32 +

33 +Used to manage teams in organizations, and change team memberships. Does not

34 +handle permissions for packages.

35 +

36 +Teams must always be fully qualified with the organization/scope they belong to

37 +when operating on them, separated by a colon (`:`). That is, if you have a

38 +`newteam` team in an `org` organization, you must always refer to that team

39 +as `@org:newteam` in these commands.

40 +

41 +If you have two-factor authentication enabled in `auth-and-writes` mode, then

42 +you can provide a code from your authenticator with `[--otp <otpcode>]`.

43 +If you don't include this then you will be prompted.

44 +

45 +* create / destroy:

46 + Create a new team, or destroy an existing one. Note: You cannot remove the

47 + `developers` team, <a href="https://docs.npmjs.com/about-developers-team" target="_blank">learn more.</a>

48 +

49 + Here's how to create a new team `newteam` under the `org` org:

50 +

51 + ```bash

52 + npm team create @org:newteam

53 + ```

54 +

55 + You should see a confirming message such as: `+@org:newteam` once the new

56 + team has been created.

57 +

58 +* add:

59 + Add a user to an existing team.

60 +

61 + Adding a new user `username` to a team named `newteam` under the `org` org:

62 +

63 + ```bash

64 + npm team add @org:newteam username

65 + ```

66 +

67 + On success, you should see a message: `username added to @org:newteam`

68 +

69 +* rm:

70 + Using `npm team rm` you can also remove users from a team they belong to.

71 +

72 + Here's an example removing user `username` from `newteam` team

73 + in `org` organization:

74 +

75 + ```bash

76 + npm team rm @org:newteam username

77 + ```

78 +

79 + Once the user is removed a confirmation message is displayed:

80 + `username removed from @org:newteam`

81 +

82 +* ls:

83 + If performed on an organization name, will return a list of existing teams

84 + under that organization. If performed on a team, it will instead return a list

85 + of all users belonging to that particular team.

86 +

87 + Here's an example of how to list all teams from an org named `org`:

88 +

89 + ```bash

90 + npm team ls @org

91 + ```

92 +

93 + Example listing all members of a team named `newteam`:

94 +

95 + ```bash

96 + npm team ls @org:newteam

97 + ```

98 +

99 +### Details

100 +

101 +`npm team` always operates directly on the current registry, configurable from

102 +the command line using `--registry=<registry url>`.

103 +

104 +You must be a *team admin* to create teams and manage team membership, under

105 +the given organization. Listing teams and team memberships may be done by

106 +any member of the organization.

107 +

108 +Organization creation and management of team admins and *organization* members

109 +is done through the website, not the npm CLI.

110 +

111 +To use teams to manage permissions on packages belonging to your organization,

112 +use the `npm access` command to grant or revoke the appropriate permissions.

113 +

114 +### Configuration

115 +

116 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

117 +<!-- automatically generated, do not edit manually -->

118 +<!-- see lib/utils/config/definitions.js -->

119 +#### `registry`

120 +

121 +* Default: "https://registry.npmjs.org/"

122 +* Type: URL

123 +

124 +The base URL of the npm registry.

125 +

126 +<!-- automatically generated, do not edit manually -->

127 +<!-- see lib/utils/config/definitions.js -->

128 +

129 +#### `otp`

130 +

131 +* Default: null

132 +* Type: null or String

133 +

134 +This is a one-time password from a two-factor authenticator. It's needed

135 +when publishing or changing package permissions with `npm access`.

136 +

137 +If not set, and a registry response fails with a challenge for a one-time

138 +password, npm will prompt on the command line for one.

139 +

140 +<!-- automatically generated, do not edit manually -->

141 +<!-- see lib/utils/config/definitions.js -->

142 +

143 +#### `parseable`

144 +

145 +* Default: false

146 +* Type: Boolean

147 +

148 +Output parseable results from commands that write to standard output. For

149 +`npm search`, this will be tab-separated table format.

150 +

151 +<!-- automatically generated, do not edit manually -->

152 +<!-- see lib/utils/config/definitions.js -->

153 +

154 +#### `json`

155 +

156 +* Default: false

157 +* Type: Boolean

158 +

159 +Whether or not to output JSON data, rather than the normal output.

160 +

161 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

162 + saving them to your `package.json`.

163 +

164 +Not supported by all npm commands.

165 +

166 +<!-- automatically generated, do not edit manually -->

167 +<!-- see lib/utils/config/definitions.js -->

168 +

169 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

170 +

171 +### See Also

172 +

173 +* [npm access](/cli/v8/commands/npm-access)

174 +* [npm config](/cli/v8/commands/npm-config)

175 +* [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/commands/npm-test.md new

+87

@@ -0,0 +1,87 @@

1 +---

2 +title: npm-test

3 +section: 1

4 +description: Test a package

5 +redirect_from:

6 + - /cli/test

7 + - /cli/test.html

8 + - /cli/commands/test

9 + - /cli-commands/test

10 + - /cli-commands/test.html

11 + - /cli-commands/npm-test

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-test.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm test [-- <args>]

21 +

22 +aliases: t, tst

23 +```

24 +

25 +### Description

26 +

27 +This runs a predefined command specified in the `"test"` property of

28 +a package's `"scripts"` object.

29 +

30 +### Example

31 +

32 +```json

33 +{

34 + "scripts": {

35 + "test": "node test.js"

36 + }

37 +}

38 +```

39 +

40 +```bash

41 +npm test

42 +> npm@x.x.x test

43 +> node test.js

44 +

45 +(test.js output would be here)

46 +```

47 +

48 +### Configuration

49 +

50 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

51 +<!-- automatically generated, do not edit manually -->

52 +<!-- see lib/utils/config/definitions.js -->

53 +#### `ignore-scripts`

54 +

55 +* Default: false

56 +* Type: Boolean

57 +

58 +If true, npm does not run scripts specified in package.json files.

59 +

60 +Note that commands explicitly intended to run a particular script, such as

61 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

62 +will still run their intended script if `ignore-scripts` is set, but they

63 +will *not* run any pre- or post-scripts.

64 +

65 +<!-- automatically generated, do not edit manually -->

66 +<!-- see lib/utils/config/definitions.js -->

67 +

68 +#### `script-shell`

69 +

70 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

71 +* Type: null or String

72 +

73 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

74 +init <pkg>` commands.

75 +

76 +<!-- automatically generated, do not edit manually -->

77 +<!-- see lib/utils/config/definitions.js -->

78 +

79 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

80 +

81 +### See Also

82 +

83 +* [npm run-script](/cli/v8/commands/npm-run-script)

84 +* [npm scripts](/cli/v8/using-npm/scripts)

85 +* [npm start](/cli/v8/commands/npm-start)

86 +* [npm restart](/cli/v8/commands/npm-restart)

87 +* [npm stop](/cli/v8/commands/npm-stop)

content/cli/v8/commands/npm-token.md new

+148

@@ -0,0 +1,148 @@

1 +---

2 +title: npm-token

3 +section: 1

4 +description: Manage your authentication tokens

5 +redirect_from:

6 + - /cli/token

7 + - /cli/token.html

8 + - /cli/commands/token

9 + - /cli-commands/token

10 + - /cli-commands/token.html

11 + - /cli-commands/npm-token

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-token.md

15 +---

16 +

17 +### Synopsis

18 +```bash

19 + npm token list [--json|--parseable]

20 + npm token create [--read-only] [--cidr=1.1.1.1/24,2.2.2.2/16]

21 + npm token revoke <id|token>

22 +```

23 +

24 +Note: This command is unaware of workspaces.

25 +

26 +### Description

27 +

28 +This lets you list, create and revoke authentication tokens.

29 +

30 +* `npm token list`:

31 + Shows a table of all active authentication tokens. You can request

32 + this as JSON with `--json` or tab-separated values with `--parseable`.

33 +

34 +```bash

35 ++--------+---------+------------+----------+----------------+

36 +| id | token | created | read-only | CIDR whitelist |

37 ++--------+---------+------------+----------+----------------+

38 +| 7f3134 | 1fa9ba… | 2017-10-02 | yes | |

39 ++--------+---------+------------+----------+----------------+

40 +| c03241 | af7aef… | 2017-10-02 | no | 192.168.0.1/24 |

41 ++--------+---------+------------+----------+----------------+

42 +| e0cf92 | 3a436a… | 2017-10-02 | no | |

43 ++--------+---------+------------+----------+----------------+

44 +| 63eb9d | 74ef35… | 2017-09-28 | no | |

45 ++--------+---------+------------+----------+----------------+

46 +| 2daaa8 | cbad5f… | 2017-09-26 | no | |

47 ++--------+---------+------------+----------+----------------+

48 +| 68c2fe | 127e51… | 2017-09-23 | no | |

49 ++--------+---------+------------+----------+----------------+

50 +| 6334e1 | 1dadd1… | 2017-09-23 | no | |

51 ++--------+---------+------------+----------+----------------+

52 +```

53 +

54 +* `npm token create [--read-only] [--cidr=<cidr-ranges>]`:

55 + Create a new authentication token. It can be `--read-only`, or accept

56 + a list of

57 + [CIDR](https://en.wikipedia.org/wiki/Classless_Inter-Domain_Routing)

58 + ranges with which to limit use of this token. This will prompt you for

59 + your password, and, if you have two-factor authentication enabled, an

60 + otp.

61 +

62 + Currently, the cli can not generate automation tokens. Please refer to

63 + the [docs

64 + website](https://docs.npmjs.com/creating-and-viewing-access-tokens)

65 + for more information on generating automation tokens.

66 +

67 +```bash

68 ++----------------+--------------------------------------+

69 +| token | a73c9572-f1b9-8983-983d-ba3ac3cc913d |

70 ++----------------+--------------------------------------+

71 +| cidr_whitelist | |

72 ++----------------+--------------------------------------+

73 +| readonly | false |

74 ++----------------+--------------------------------------+

75 +| created | 2017-10-02T07:52:24.838Z |

76 ++----------------+--------------------------------------+

77 +```

78 +

79 +* `npm token revoke <token|id>`:

80 + Immediately removes an authentication token from the registry. You

81 + will no longer be able to use it. This can accept both complete

82 + tokens (such as those you get back from `npm token create`, and those

83 + found in your `.npmrc`), and ids as seen in the parseable or json

84 + output of `npm token list`. This will NOT accept the truncated token

85 + found in the normal `npm token list` output.

86 +

87 +### Configuration

88 +

89 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

90 +<!-- automatically generated, do not edit manually -->

91 +<!-- see lib/utils/config/definitions.js -->

92 +#### `read-only`

93 +

94 +* Default: false

95 +* Type: Boolean

96 +

97 +This is used to mark a token as unable to publish when configuring limited

98 +access tokens with the `npm token create` command.

99 +

100 +<!-- automatically generated, do not edit manually -->

101 +<!-- see lib/utils/config/definitions.js -->

102 +

103 +#### `cidr`

104 +

105 +* Default: null

106 +* Type: null or String (can be set multiple times)

107 +

108 +This is a list of CIDR address to be used when configuring limited access

109 +tokens with the `npm token create` command.

110 +

111 +<!-- automatically generated, do not edit manually -->

112 +<!-- see lib/utils/config/definitions.js -->

113 +

114 +#### `registry`

115 +

116 +* Default: "https://registry.npmjs.org/"

117 +* Type: URL

118 +

119 +The base URL of the npm registry.

120 +

121 +<!-- automatically generated, do not edit manually -->

122 +<!-- see lib/utils/config/definitions.js -->

123 +

124 +#### `otp`

125 +

126 +* Default: null

127 +* Type: null or String

128 +

129 +This is a one-time password from a two-factor authenticator. It's needed

130 +when publishing or changing package permissions with `npm access`.

131 +

132 +If not set, and a registry response fails with a challenge for a one-time

133 +password, npm will prompt on the command line for one.

134 +

135 +<!-- automatically generated, do not edit manually -->

136 +<!-- see lib/utils/config/definitions.js -->

137 +

138 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

139 +

140 +### See Also

141 +

142 +* [npm adduser](/cli/v8/commands/npm-adduser)

143 +* [npm registry](/cli/v8/using-npm/registry)

144 +* [npm config](/cli/v8/commands/npm-config)

145 +* [npmrc](/cli/v8/configuring-npm/npmrc)

146 +* [npm owner](/cli/v8/commands/npm-owner)

147 +* [npm whoami](/cli/v8/commands/npm-whoami)

148 +* [npm profile](/cli/v8/commands/npm-profile)

content/cli/v8/commands/npm-uninstall.md new

+153

@@ -0,0 +1,153 @@

1 +---

2 +title: npm-uninstall

3 +section: 1

4 +description: Remove a package

5 +redirect_from:

6 + - /cli/uninstall

7 + - /cli/uninstall.html

8 + - /cli/commands/uninstall

9 + - /cli-commands/uninstall

10 + - /cli-commands/uninstall.html

11 + - /cli-commands/npm-uninstall

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-uninstall.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm uninstall [<@scope>/]<pkg>[@<version>]... [-S|--save|--no-save]

21 +

22 +aliases: remove, rm, r, un, unlink

23 +```

24 +

25 +### Description

26 +

27 +This uninstalls a package, completely removing everything npm installed

28 +on its behalf.

29 +

30 +It also removes the package from the `dependencies`, `devDependencies`,

31 +`optionalDependencies`, and `peerDependencies` objects in your

32 +`package.json`.

33 +

34 +Futher, if you have an `npm-shrinkwrap.json` or `package-lock.json`, npm

35 +will update those files as well.

36 +

37 +`--no-save` will tell npm not to remove the package from your

38 +`package.json`, `npm-shrinkwrap.json`, or `package-lock.json` files.

39 +

40 +`--save` or `-S` will tell npm to remove the package from your

41 +`package.json`, `npm-shrinkwrap.json`, and `package-lock.json` files.

42 +This is the default, but you may need to use this if you have for

43 +instance `save=false` in your `npmrc` file

44 +

45 +In global mode (ie, with `-g` or `--global` appended to the command),

46 +it uninstalls the current package context as a global package.

47 +`--no-save` is ignored in this case.

48 +

49 +Scope is optional and follows the usual rules for [`scope`](/cli/v8/using-npm/scope).

50 +

51 +### Examples

52 +

53 +```bash

54 +npm uninstall sax

55 +```

56 +

57 +`sax` will no longer be in your `package.json`, `npm-shrinkwrap.json`, or

58 +`package-lock.json` files.

59 +

60 +```bash

61 +npm uninstall lodash --no-save

62 +```

63 +

64 +`lodash` will not be removed from your `package.json`,

65 +`npm-shrinkwrap.json`, or `package-lock.json` files.

66 +

67 +### Configuration

68 +

69 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

70 +<!-- automatically generated, do not edit manually -->

71 +<!-- see lib/utils/config/definitions.js -->

72 +#### `save`

73 +

74 +* Default: true

75 +* Type: Boolean

76 +

77 +Save installed packages to a package.json file as dependencies.

78 +

79 +When used with the `npm rm` command, removes the dependency from

80 +package.json.

81 +

82 +<!-- automatically generated, do not edit manually -->

83 +<!-- see lib/utils/config/definitions.js -->

84 +

85 +#### `workspace`

86 +

87 +* Default:

88 +* Type: String (can be set multiple times)

89 +

90 +Enable running a command in the context of the configured workspaces of the

91 +current project while filtering by running only the workspaces defined by

92 +this configuration option.

93 +

94 +Valid values for the `workspace` config are either:

95 +

96 +* Workspace names

97 +* Path to a workspace directory

98 +* Path to a parent workspace directory (will result in selecting all

99 + workspaces within that folder)

100 +

101 +When set for the `npm init` command, this may be set to the folder of a

102 +workspace which does not yet exist, to create the folder and set it up as a

103 +brand new workspace within the project.

104 +

105 +This value is not exported to the environment for child processes.

106 +

107 +<!-- automatically generated, do not edit manually -->

108 +<!-- see lib/utils/config/definitions.js -->

109 +

110 +#### `workspaces`

111 +

112 +* Default: null

113 +* Type: null or Boolean

114 +

115 +Set to true to run the command in the context of **all** configured

116 +workspaces.

117 +

118 +Explicitly setting this to false will cause commands like `install` to

119 +ignore workspaces altogether. When not set explicitly:

120 +

121 +- Commands that operate on the `node_modules` tree (install, update, etc.)

122 +will link workspaces into the `node_modules` folder. - Commands that do

123 +other things (test, exec, publish, etc.) will operate on the root project,

124 +_unless_ one or more workspaces are specified in the `workspace` config.

125 +

126 +This value is not exported to the environment for child processes.

127 +

128 +<!-- automatically generated, do not edit manually -->

129 +<!-- see lib/utils/config/definitions.js -->

130 +

131 +#### `include-workspace-root`

132 +

133 +* Default: false

134 +* Type: Boolean

135 +

136 +Include the workspace root when workspaces are enabled for a command.

137 +

138 +When false, specifying individual workspaces via the `workspace` config, or

139 +all workspaces via the `workspaces` flag, will cause npm to operate only on

140 +the specified workspaces, and not on the root project.

141 +

142 +<!-- automatically generated, do not edit manually -->

143 +<!-- see lib/utils/config/definitions.js -->

144 +

145 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

146 +

147 +### See Also

148 +

149 +* [npm prune](/cli/v8/commands/npm-prune)

150 +* [npm install](/cli/v8/commands/npm-install)

151 +* [npm folders](/cli/v8/configuring-npm/folders)

152 +* [npm config](/cli/v8/commands/npm-config)

153 +* [npmrc](/cli/v8/configuring-npm/npmrc)

content/cli/v8/commands/npm-unpublish.md new

+162

@@ -0,0 +1,162 @@

1 +---

2 +title: npm-unpublish

3 +section: 1

4 +description: Remove a package from the registry

5 +redirect_from:

6 + - /cli/unpublish

7 + - /cli/unpublish.html

8 + - /cli/commands/unpublish

9 + - /cli-commands/unpublish

10 + - /cli-commands/unpublish.html

11 + - /cli-commands/npm-unpublish

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-unpublish.md

15 +---

16 +

17 +### Synopsis

18 +

19 +To learn more about how the npm registry treats unpublish, see our <a

20 +href="https://docs.npmjs.com/policies/unpublish" target="_blank"

21 +rel="noopener noreferrer"> unpublish policies</a>

22 +

23 +#### Unpublishing a single version of a package

24 +

25 +```bash

26 +npm unpublish [<@scope>/]<pkg>@<version>

27 +```

28 +

29 +#### Unpublishing an entire package

30 +

31 +```bash

32 +npm unpublish [<@scope>/]<pkg> --force

33 +```

34 +

35 +### Warning

36 +

37 +Consider using the [`deprecate`](/cli/v8/commands/npm-deprecate) command instead,

38 +if your intent is to encourage users to upgrade, or if you no longer

39 +want to maintain a package.

40 +

41 +### Description

42 +

43 +This removes a package version from the registry, deleting its entry and

44 +removing the tarball.

45 +

46 +The npm registry will return an error if you are not [logged

47 +in](/cli/v8/commands/npm-adduser).

48 +

49 +If you do not specify a version or if you remove all of a package's

50 +versions then the registry will remove the root package entry entirely.

51 +

52 +Even if you unpublish a package version, that specific name and version

53 +combination can never be reused. In order to publish the package again,

54 +you must use a new version number. If you unpublish the entire package,

55 +you may not publish any new versions of that package until 24 hours have

56 +passed.

57 +

58 +### Configuration

59 +

60 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

61 +<!-- automatically generated, do not edit manually -->

62 +<!-- see lib/utils/config/definitions.js -->

63 +#### `dry-run`

64 +

65 +* Default: false

66 +* Type: Boolean

67 +

68 +Indicates that you don't want npm to make any changes and that it should

69 +only report what it would have done. This can be passed into any of the

70 +commands that modify your local installation, eg, `install`, `update`,

71 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

72 +

73 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

74 +`owner`, etc.

75 +

76 +<!-- automatically generated, do not edit manually -->

77 +<!-- see lib/utils/config/definitions.js -->

78 +

79 +#### `force`

80 +

81 +* Default: false

82 +* Type: Boolean

83 +

84 +Removes various protections against unfortunate side effects, common

85 +mistakes, unnecessary performance degradation, and malicious input.

86 +

87 +* Allow clobbering non-npm files in global installs.

88 +* Allow the `npm version` command to work on an unclean git repository.

89 +* Allow deleting the cache folder with `npm cache clean`.

90 +* Allow installing packages that have an `engines` declaration requiring a

91 + different version of npm.

92 +* Allow installing packages that have an `engines` declaration requiring a

93 + different version of `node`, even if `--engine-strict` is enabled.

94 +* Allow `npm audit fix` to install modules outside your stated dependency

95 + range (including SemVer-major changes).

96 +* Allow unpublishing all versions of a published package.

97 +* Allow conflicting peerDependencies to be installed in the root project.

98 +* Implicitly set `--yes` during `npm init`.

99 +* Allow clobbering existing values in `npm pkg`

100 +

101 +If you don't have a clear idea of what you want to do, it is strongly

102 +recommended that you do not use this option!

103 +

104 +<!-- automatically generated, do not edit manually -->

105 +<!-- see lib/utils/config/definitions.js -->

106 +

107 +#### `workspace`

108 +

109 +* Default:

110 +* Type: String (can be set multiple times)

111 +

112 +Enable running a command in the context of the configured workspaces of the

113 +current project while filtering by running only the workspaces defined by

114 +this configuration option.

115 +

116 +Valid values for the `workspace` config are either:

117 +

118 +* Workspace names

119 +* Path to a workspace directory

120 +* Path to a parent workspace directory (will result in selecting all

121 + workspaces within that folder)

122 +

123 +When set for the `npm init` command, this may be set to the folder of a

124 +workspace which does not yet exist, to create the folder and set it up as a

125 +brand new workspace within the project.

126 +

127 +This value is not exported to the environment for child processes.

128 +

129 +<!-- automatically generated, do not edit manually -->

130 +<!-- see lib/utils/config/definitions.js -->

131 +

132 +#### `workspaces`

133 +

134 +* Default: null

135 +* Type: null or Boolean

136 +

137 +Set to true to run the command in the context of **all** configured

138 +workspaces.

139 +

140 +Explicitly setting this to false will cause commands like `install` to

141 +ignore workspaces altogether. When not set explicitly:

142 +

143 +- Commands that operate on the `node_modules` tree (install, update, etc.)

144 +will link workspaces into the `node_modules` folder. - Commands that do

145 +other things (test, exec, publish, etc.) will operate on the root project,

146 +_unless_ one or more workspaces are specified in the `workspace` config.

147 +

148 +This value is not exported to the environment for child processes.

149 +

150 +<!-- automatically generated, do not edit manually -->

151 +<!-- see lib/utils/config/definitions.js -->

152 +

153 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

154 +

155 +### See Also

156 +

157 +* [npm deprecate](/cli/v8/commands/npm-deprecate)

158 +* [npm publish](/cli/v8/commands/npm-publish)

159 +* [npm registry](/cli/v8/using-npm/registry)

160 +* [npm adduser](/cli/v8/commands/npm-adduser)

161 +* [npm owner](/cli/v8/commands/npm-owner)

162 +* [npm login](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm-unstar.md new

+92

@@ -0,0 +1,92 @@

1 +---

2 +title: npm-unstar

3 +section: 1

4 +description: Remove an item from your favorite packages

5 +redirect_from:

6 + - /cli/unstar

7 + - /cli/unstar.html

8 + - /cli/commands/unstar

9 + - /cli-commands/unstar

10 + - /cli-commands/unstar.html

11 + - /cli-commands/npm-unstar

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-unstar.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm unstar [<pkg>...]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +"Unstarring" a package is the opposite of [`npm star`](/cli/v8/commands/npm-star),

28 +it removes an item from your list of favorite packages.

29 +

30 +### More

31 +

32 +There's also these extra commands to help you manage your favorite packages:

33 +

34 +#### Star

35 +

36 +You can "star" a package using [`npm star`](/cli/v8/commands/npm-star)

37 +

38 +#### Listing stars

39 +

40 +You can see all your starred packages using [`npm stars`](/cli/v8/commands/npm-stars)

41 +

42 +### Configuration

43 +

44 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

45 +<!-- automatically generated, do not edit manually -->

46 +<!-- see lib/utils/config/definitions.js -->

47 +#### `registry`

48 +

49 +* Default: "https://registry.npmjs.org/"

50 +* Type: URL

51 +

52 +The base URL of the npm registry.

53 +

54 +<!-- automatically generated, do not edit manually -->

55 +<!-- see lib/utils/config/definitions.js -->

56 +

57 +#### `unicode`

58 +

59 +* Default: false on windows, true on mac/unix systems with a unicode locale,

60 + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables.

61 +* Type: Boolean

62 +

63 +When set to true, npm uses unicode characters in the tree output. When

64 +false, it uses ascii characters instead of unicode glyphs.

65 +

66 +<!-- automatically generated, do not edit manually -->

67 +<!-- see lib/utils/config/definitions.js -->

68 +

69 +#### `otp`

70 +

71 +* Default: null

72 +* Type: null or String

73 +

74 +This is a one-time password from a two-factor authenticator. It's needed

75 +when publishing or changing package permissions with `npm access`.

76 +

77 +If not set, and a registry response fails with a challenge for a one-time

78 +password, npm will prompt on the command line for one.

79 +

80 +<!-- automatically generated, do not edit manually -->

81 +<!-- see lib/utils/config/definitions.js -->

82 +

83 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

84 +

85 +### See Also

86 +

87 +* [npm star](/cli/v8/commands/npm-star)

88 +* [npm stars](/cli/v8/commands/npm-stars)

89 +* [npm view](/cli/v8/commands/npm-view)

90 +* [npm whoami](/cli/v8/commands/npm-whoami)

91 +* [npm adduser](/cli/v8/commands/npm-adduser)

92 +

content/cli/v8/commands/npm-update.md new

+410

@@ -0,0 +1,410 @@

1 +---

2 +title: npm-update

3 +section: 1

4 +description: Update packages

5 +redirect_from:

6 + - /cli/update

7 + - /cli/update.html

8 + - /cli/commands/update

9 + - /cli-commands/update

10 + - /cli-commands/update.html

11 + - /cli-commands/npm-update

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-update.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm update [-g] [<pkg>...]

21 +

22 +aliases: up, upgrade

23 +```

24 +

25 +### Description

26 +

27 +This command will update all the packages listed to the latest version

28 +(specified by the `tag` config), respecting the semver constraints of

29 +both your package and its dependencies (if they also require the same

30 +package).

31 +

32 +It will also install missing packages.

33 +

34 +If the `-g` flag is specified, this command will update globally installed

35 +packages.

36 +

37 +If no package name is specified, all packages in the specified location (global

38 +or local) will be updated.

39 +

40 +### Example

41 +

42 +For the examples below, assume that the current package is `app` and it depends

43 +on dependencies, `dep1` (`dep2`, .. etc.). The published versions of `dep1`

44 +are:

45 +

46 +```json

47 +{

48 + "dist-tags": { "latest": "1.2.2" },

49 + "versions": [

50 + "1.2.2",

51 + "1.2.1",

52 + "1.2.0",

53 + "1.1.2",

54 + "1.1.1",

55 + "1.0.0",

56 + "0.4.1",

57 + "0.4.0",

58 + "0.2.0"

59 + ]

60 +}

61 +```

62 +

63 +#### Caret Dependencies

64 +

65 +If `app`'s `package.json` contains:

66 +

67 +```json

68 +"dependencies": {

69 + "dep1": "^1.1.1"

70 +}

71 +```

72 +

73 +Then `npm update` will install `dep1@1.2.2`, because `1.2.2` is `latest` and

74 +`1.2.2` satisfies `^1.1.1`.

75 +

76 +#### Tilde Dependencies

77 +

78 +However, if `app`'s `package.json` contains:

79 +

80 +```json

81 +"dependencies": {

82 + "dep1": "~1.1.1"

83 +}

84 +```

85 +

86 +In this case, running `npm update` will install `dep1@1.1.2`. Even though the

87 +`latest` tag points to `1.2.2`, this version do not satisfy `~1.1.1`, which is

88 +equivalent to `>=1.1.1 <1.2.0`. So the highest-sorting version that satisfies

89 +`~1.1.1` is used, which is `1.1.2`.

90 +

91 +#### Caret Dependencies below 1.0.0

92 +

93 +Suppose `app` has a caret dependency on a version below `1.0.0`, for example:

94 +

95 +```json

96 +"dependencies": {

97 + "dep1": "^0.2.0"

98 +}

99 +```

100 +

101 +`npm update` will install `dep1@0.2.0`, because there are no other

102 +versions which satisfy `^0.2.0`.

103 +

104 +If the dependence were on `^0.4.0`:

105 +

106 +```json

107 +"dependencies": {

108 + "dep1": "^0.4.0"

109 +}

110 +```

111 +

112 +Then `npm update` will install `dep1@0.4.1`, because that is the highest-sorting

113 +version that satisfies `^0.4.0` (`>= 0.4.0 <0.5.0`)

114 +

115 +

116 +#### Subdependencies

117 +

118 +Suppose your app now also has a dependency on `dep2`

119 +

120 +```json

121 +{

122 + "name": "my-app",

123 + "dependencies": {

124 + "dep1": "^1.0.0",

125 + "dep2": "1.0.0"

126 + }

127 +}

128 +```

129 +

130 +and `dep2` itself depends on this limited range of `dep1`

131 +

132 +```json

133 +{

134 +"name": "dep2",

135 + "dependencies": {

136 + "dep1": "~1.1.1"

137 + }

138 +}

139 +```

140 +

141 +Then `npm update` will install `dep1@1.1.2` because that is the highest

142 +version that `dep2` allows. npm will prioritize having a single version

143 +of `dep1` in your tree rather than two when that single version can

144 +satisfy the semver requirements of multiple dependencies in your tree.

145 +In this case if you really did need your package to use a newer version

146 +you would need to use `npm install`.

147 +

148 +

149 +#### Updating Globally-Installed Packages

150 +

151 +`npm update -g` will apply the `update` action to each globally installed

152 +package that is `outdated` -- that is, has a version that is different from

153 +`wanted`.

154 +

155 +Note: Globally installed packages are treated as if they are installed with a

156 +caret semver range specified. So if you require to update to `latest` you may

157 +need to run `npm install -g [<pkg>...]`

158 +

159 +NOTE: If a package has been upgraded to a version newer than `latest`, it will

160 +be _downgraded_.

161 +

162 +### Configuration

163 +

164 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

165 +<!-- automatically generated, do not edit manually -->

166 +<!-- see lib/utils/config/definitions.js -->

167 +#### `global`

168 +

169 +* Default: false

170 +* Type: Boolean

171 +

172 +Operates in "global" mode, so that packages are installed into the `prefix`

173 +folder instead of the current working directory. See

174 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

175 +

176 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

177 + of the current working directory.

178 +* bin files are linked to `{prefix}/bin`

179 +* man pages are linked to `{prefix}/share/man`

180 +

181 +<!-- automatically generated, do not edit manually -->

182 +<!-- see lib/utils/config/definitions.js -->

183 +

184 +#### `global-style`

185 +

186 +* Default: false

187 +* Type: Boolean

188 +

189 +Causes npm to install the package into your local `node_modules` folder with

190 +the same layout it uses with the global `node_modules` folder. Only your

191 +direct dependencies will show in `node_modules` and everything they depend

192 +on will be flattened in their `node_modules` folders. This obviously will

193 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

194 +will be preferred.

195 +

196 +<!-- automatically generated, do not edit manually -->

197 +<!-- see lib/utils/config/definitions.js -->

198 +

199 +#### `legacy-bundling`

200 +

201 +* Default: false

202 +* Type: Boolean

203 +

204 +Causes npm to install the package such that versions of npm prior to 1.4,

205 +such as the one included with node 0.8, can install the package. This

206 +eliminates all automatic deduping. If used with `global-style` this option

207 +will be preferred.

208 +

209 +<!-- automatically generated, do not edit manually -->

210 +<!-- see lib/utils/config/definitions.js -->

211 +

212 +#### `strict-peer-deps`

213 +

214 +* Default: false

215 +* Type: Boolean

216 +

217 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

218 +conflicting `peerDependencies` will be treated as an install failure, even

219 +if npm could reasonably guess the appropriate resolution based on non-peer

220 +dependency relationships.

221 +

222 +By default, conflicting `peerDependencies` deep in the dependency graph will

223 +be resolved using the nearest non-peer dependency specification, even if

224 +doing so will result in some packages receiving a peer dependency outside

225 +the range set in their package's `peerDependencies` object.

226 +

227 +When such and override is performed, a warning is printed, explaining the

228 +conflict and the packages involved. If `--strict-peer-deps` is set, then

229 +this warning is treated as a failure.

230 +

231 +<!-- automatically generated, do not edit manually -->

232 +<!-- see lib/utils/config/definitions.js -->

233 +

234 +#### `package-lock`

235 +

236 +* Default: true

237 +* Type: Boolean

238 +

239 +If set to false, then ignore `package-lock.json` files when installing. This

240 +will also prevent _writing_ `package-lock.json` if `save` is true.

241 +

242 +When package package-locks are disabled, automatic pruning of extraneous

243 +modules will also be disabled. To remove extraneous modules with

244 +package-locks disabled use `npm prune`.

245 +

246 +<!-- automatically generated, do not edit manually -->

247 +<!-- see lib/utils/config/definitions.js -->

248 +

249 +#### `omit`

250 +

251 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

252 + 'production', otherwise empty.

253 +* Type: "dev", "optional", or "peer" (can be set multiple times)

254 +

255 +Dependency types to omit from the installation tree on disk.

256 +

257 +Note that these dependencies _are_ still resolved and added to the

258 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

259 +physically installed on disk.

260 +

261 +If a package type appears in both the `--include` and `--omit` lists, then

262 +it will be included.

263 +

264 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

265 +variable will be set to `'production'` for all lifecycle scripts.

266 +

267 +<!-- automatically generated, do not edit manually -->

268 +<!-- see lib/utils/config/definitions.js -->

269 +

270 +#### `ignore-scripts`

271 +

272 +* Default: false

273 +* Type: Boolean

274 +

275 +If true, npm does not run scripts specified in package.json files.

276 +

277 +Note that commands explicitly intended to run a particular script, such as

278 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

279 +will still run their intended script if `ignore-scripts` is set, but they

280 +will *not* run any pre- or post-scripts.

281 +

282 +<!-- automatically generated, do not edit manually -->

283 +<!-- see lib/utils/config/definitions.js -->

284 +

285 +#### `audit`

286 +

287 +* Default: true

288 +* Type: Boolean

289 +

290 +When "true" submit audit reports alongside the current npm command to the

291 +default registry and all registries configured for scopes. See the

292 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

293 +submitted.

294 +

295 +<!-- automatically generated, do not edit manually -->

296 +<!-- see lib/utils/config/definitions.js -->

297 +

298 +#### `bin-links`

299 +

300 +* Default: true

301 +* Type: Boolean

302 +

303 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

304 +executables.

305 +

306 +Set to false to have it not do this. This can be used to work around the

307 +fact that some file systems don't support symlinks, even on ostensibly Unix

308 +systems.

309 +

310 +<!-- automatically generated, do not edit manually -->

311 +<!-- see lib/utils/config/definitions.js -->

312 +

313 +#### `fund`

314 +

315 +* Default: true

316 +* Type: Boolean

317 +

318 +When "true" displays the message at the end of each `npm install`

319 +acknowledging the number of dependencies looking for funding. See [`npm

320 +fund`](/cli/v8/commands/npm-fund) for details.

321 +

322 +<!-- automatically generated, do not edit manually -->

323 +<!-- see lib/utils/config/definitions.js -->

324 +

325 +#### `dry-run`

326 +

327 +* Default: false

328 +* Type: Boolean

329 +

330 +Indicates that you don't want npm to make any changes and that it should

331 +only report what it would have done. This can be passed into any of the

332 +commands that modify your local installation, eg, `install`, `update`,

333 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

334 +

335 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

336 +`owner`, etc.

337 +

338 +<!-- automatically generated, do not edit manually -->

339 +<!-- see lib/utils/config/definitions.js -->

340 +

341 +#### `workspace`

342 +

343 +* Default:

344 +* Type: String (can be set multiple times)

345 +

346 +Enable running a command in the context of the configured workspaces of the

347 +current project while filtering by running only the workspaces defined by

348 +this configuration option.

349 +

350 +Valid values for the `workspace` config are either:

351 +

352 +* Workspace names

353 +* Path to a workspace directory

354 +* Path to a parent workspace directory (will result in selecting all

355 + workspaces within that folder)

356 +

357 +When set for the `npm init` command, this may be set to the folder of a

358 +workspace which does not yet exist, to create the folder and set it up as a

359 +brand new workspace within the project.

360 +

361 +This value is not exported to the environment for child processes.

362 +

363 +<!-- automatically generated, do not edit manually -->

364 +<!-- see lib/utils/config/definitions.js -->

365 +

366 +#### `workspaces`

367 +

368 +* Default: null

369 +* Type: null or Boolean

370 +

371 +Set to true to run the command in the context of **all** configured

372 +workspaces.

373 +

374 +Explicitly setting this to false will cause commands like `install` to

375 +ignore workspaces altogether. When not set explicitly:

376 +

377 +- Commands that operate on the `node_modules` tree (install, update, etc.)

378 +will link workspaces into the `node_modules` folder. - Commands that do

379 +other things (test, exec, publish, etc.) will operate on the root project,

380 +_unless_ one or more workspaces are specified in the `workspace` config.

381 +

382 +This value is not exported to the environment for child processes.

383 +

384 +<!-- automatically generated, do not edit manually -->

385 +<!-- see lib/utils/config/definitions.js -->

386 +

387 +#### `include-workspace-root`

388 +

389 +* Default: false

390 +* Type: Boolean

391 +

392 +Include the workspace root when workspaces are enabled for a command.

393 +

394 +When false, specifying individual workspaces via the `workspace` config, or

395 +all workspaces via the `workspaces` flag, will cause npm to operate only on

396 +the specified workspaces, and not on the root project.

397 +

398 +<!-- automatically generated, do not edit manually -->

399 +<!-- see lib/utils/config/definitions.js -->

400 +

401 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

402 +

403 +### See Also

404 +

405 +* [npm install](/cli/v8/commands/npm-install)

406 +* [npm outdated](/cli/v8/commands/npm-outdated)

407 +* [npm shrinkwrap](/cli/v8/commands/npm-shrinkwrap)

408 +* [npm registry](/cli/v8/using-npm/registry)

409 +* [npm folders](/cli/v8/configuring-npm/folders)

410 +* [npm ls](/cli/v8/commands/npm-ls)

content/cli/v8/commands/npm-version.md new

+254

@@ -0,0 +1,254 @@

1 +---

2 +title: npm-version

3 +section: 1

4 +description: Bump a package version

5 +redirect_from:

6 + - /cli/version

7 + - /cli/version.html

8 + - /cli/commands/version

9 + - /cli-commands/version

10 + - /cli-commands/version.html

11 + - /cli-commands/npm-version

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-version.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]

21 +

22 +'npm [-v | --version]' to print npm version

23 +'npm view <pkg> version' to view a package's published version

24 +'npm ls' to inspect current package/dependency versions

25 +```

26 +

27 +### Configuration

28 +

29 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

30 +<!-- automatically generated, do not edit manually -->

31 +<!-- see lib/utils/config/definitions.js -->

32 +#### `allow-same-version`

33 +

34 +* Default: false

35 +* Type: Boolean

36 +

37 +Prevents throwing an error when `npm version` is used to set the new version

38 +to the same value as the current version.

39 +

40 +<!-- automatically generated, do not edit manually -->

41 +<!-- see lib/utils/config/definitions.js -->

42 +

43 +#### `commit-hooks`

44 +

45 +* Default: true

46 +* Type: Boolean

47 +

48 +Run git commit hooks when using the `npm version` command.

49 +

50 +<!-- automatically generated, do not edit manually -->

51 +<!-- see lib/utils/config/definitions.js -->

52 +

53 +#### `git-tag-version`

54 +

55 +* Default: true

56 +* Type: Boolean

57 +

58 +Tag the commit when using the `npm version` command.

59 +

60 +<!-- automatically generated, do not edit manually -->

61 +<!-- see lib/utils/config/definitions.js -->

62 +

63 +#### `json`

64 +

65 +* Default: false

66 +* Type: Boolean

67 +

68 +Whether or not to output JSON data, rather than the normal output.

69 +

70 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

71 + saving them to your `package.json`.

72 +

73 +Not supported by all npm commands.

74 +

75 +<!-- automatically generated, do not edit manually -->

76 +<!-- see lib/utils/config/definitions.js -->

77 +

78 +#### `preid`

79 +

80 +* Default: ""

81 +* Type: String

82 +

83 +The "prerelease identifier" to use as a prefix for the "prerelease" part of

84 +a semver. Like the `rc` in `1.2.0-rc.8`.

85 +

86 +<!-- automatically generated, do not edit manually -->

87 +<!-- see lib/utils/config/definitions.js -->

88 +

89 +#### `sign-git-tag`

90 +

91 +* Default: false

92 +* Type: Boolean

93 +

94 +If set to true, then the `npm version` command will tag the version using

95 +`-s` to add a signature.

96 +

97 +Note that git requires you to have set up GPG keys in your git configs for

98 +this to work properly.

99 +

100 +<!-- automatically generated, do not edit manually -->

101 +<!-- see lib/utils/config/definitions.js -->

102 +

103 +#### `workspace`

104 +

105 +* Default:

106 +* Type: String (can be set multiple times)

107 +

108 +Enable running a command in the context of the configured workspaces of the

109 +current project while filtering by running only the workspaces defined by

110 +this configuration option.

111 +

112 +Valid values for the `workspace` config are either:

113 +

114 +* Workspace names

115 +* Path to a workspace directory

116 +* Path to a parent workspace directory (will result in selecting all

117 + workspaces within that folder)

118 +

119 +When set for the `npm init` command, this may be set to the folder of a

120 +workspace which does not yet exist, to create the folder and set it up as a

121 +brand new workspace within the project.

122 +

123 +This value is not exported to the environment for child processes.

124 +

125 +<!-- automatically generated, do not edit manually -->

126 +<!-- see lib/utils/config/definitions.js -->

127 +

128 +#### `workspaces`

129 +

130 +* Default: null

131 +* Type: null or Boolean

132 +

133 +Set to true to run the command in the context of **all** configured

134 +workspaces.

135 +

136 +Explicitly setting this to false will cause commands like `install` to

137 +ignore workspaces altogether. When not set explicitly:

138 +

139 +- Commands that operate on the `node_modules` tree (install, update, etc.)

140 +will link workspaces into the `node_modules` folder. - Commands that do

141 +other things (test, exec, publish, etc.) will operate on the root project,

142 +_unless_ one or more workspaces are specified in the `workspace` config.

143 +

144 +This value is not exported to the environment for child processes.

145 +

146 +<!-- automatically generated, do not edit manually -->

147 +<!-- see lib/utils/config/definitions.js -->

148 +

149 +#### `include-workspace-root`

150 +

151 +* Default: false

152 +* Type: Boolean

153 +

154 +Include the workspace root when workspaces are enabled for a command.

155 +

156 +When false, specifying individual workspaces via the `workspace` config, or

157 +all workspaces via the `workspaces` flag, will cause npm to operate only on

158 +the specified workspaces, and not on the root project.

159 +

160 +<!-- automatically generated, do not edit manually -->

161 +<!-- see lib/utils/config/definitions.js -->

162 +

163 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

164 +

165 +### Description

166 +

167 +Run this in a package directory to bump the version and write the new data

168 +back to `package.json`, `package-lock.json`, and, if present,

169 +`npm-shrinkwrap.json`.

170 +

171 +The `newversion` argument should be a valid semver string, a valid second

172 +argument to [semver.inc](https://github.com/npm/node-semver#functions) (one

173 +of `patch`, `minor`, `major`, `prepatch`, `preminor`, `premajor`,

174 +`prerelease`), or `from-git`. In the second case, the existing version will

175 +be incremented by 1 in the specified field. `from-git` will try to read

176 +the latest git tag, and use that as the new npm version.

177 +

178 +If run in a git repo, it will also create a version commit and tag. This

179 +behavior is controlled by `git-tag-version` (see below), and can be

180 +disabled on the command line by running `npm --no-git-tag-version version`.

181 +It will fail if the working directory is not clean, unless the `-f` or

182 +`--force` flag is set.

183 +

184 +If supplied with `-m` or `--message` config option, npm will use it as a

185 +commit message when creating a version commit. If the `message` config

186 +contains `%s` then that will be replaced with the resulting version number.

187 +For example:

188 +

189 +```bash

190 +npm version patch -m "Upgrade to %s for reasons"

191 +```

192 +

193 +If the `sign-git-tag` config is set, then the tag will be signed using the

194 +`-s` flag to git. Note that you must have a default GPG key set up in your

195 +git config for this to work properly. For example:

196 +

197 +```bash

198 +$ npm config set sign-git-tag true

199 +$ npm version patch

200 +

201 +You need a passphrase to unlock the secret key for

202 +user: "isaacs (http://blog.izs.me/) <i@izs.me>"

203 +2048-bit RSA key, ID 6C481CF6, created 2010-08-31

204 +

205 +Enter passphrase:

206 +```

207 +

208 +If `preversion`, `version`, or `postversion` are in the `scripts` property

209 +of the package.json, they will be executed as part of running `npm

210 +version`.

211 +

212 +The exact order of execution is as follows:

213 +

214 +1. Check to make sure the git working directory is clean before we get

215 + started. Your scripts may add files to the commit in future steps.

216 + This step is skipped if the `--force` flag is set.

217 +2. Run the `preversion` script. These scripts have access to the old

218 + `version` in package.json. A typical use would be running your full

219 + test suite before deploying. Any files you want added to the commit

220 + should be explicitly added using `git add`.

221 +3. Bump `version` in `package.json` as requested (`patch`, `minor`,

222 + `major`, etc).

223 +4. Run the `version` script. These scripts have access to the new `version`

224 + in package.json (so they can incorporate it into file headers in

225 + generated files for example). Again, scripts should explicitly add

226 + generated files to the commit using `git add`.

227 +5. Commit and tag.

228 +6. Run the `postversion` script. Use it to clean up the file system or

229 + automatically push the commit and/or tag.

230 +

231 +Take the following example:

232 +

233 +```json

234 +{

235 + "scripts": {

236 + "preversion": "npm test",

237 + "version": "npm run build && git add -A dist",

238 + "postversion": "git push && git push --tags && rm -rf build/temp"

239 + }

240 +}

241 +```

242 +

243 +This runs all your tests and proceeds only if they pass. Then runs your

244 +`build` script, and adds everything in the `dist` directory to the commit.

245 +After the commit, it pushes the new commit and tag up to the server, and

246 +deletes the `build/temp` directory.

247 +

248 +### See Also

249 +

250 +* [npm init](/cli/v8/commands/npm-init)

251 +* [npm run-script](/cli/v8/commands/npm-run-script)

252 +* [npm scripts](/cli/v8/using-npm/scripts)

253 +* [package.json](/cli/v8/configuring-npm/package-json)

254 +* [config](/cli/v8/using-npm/config)

content/cli/v8/commands/npm-view.md new

+209

@@ -0,0 +1,209 @@

1 +---

2 +title: npm-view

3 +section: 1

4 +description: View registry info

5 +redirect_from:

6 + - /cli/view

7 + - /cli/view.html

8 + - /cli/commands/view

9 + - /cli-commands/view

10 + - /cli-commands/view.html

11 + - /cli-commands/npm-view

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-view.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm view [<@scope>/]<name>[@<version>] [<field>[.<subfield>]...]

21 +

22 +aliases: info, show, v

23 +```

24 +

25 +### Description

26 +

27 +This command shows data about a package and prints it to stdout.

28 +

29 +As an example, to view information about the `connect` package from the registry, you would run:

30 +

31 +```bash

32 +npm view connect

33 +```

34 +

35 +The default version is `"latest"` if unspecified.

36 +

37 +Field names can be specified after the package descriptor.

38 +For example, to show the dependencies of the `ronn` package at version

39 +`0.3.5`, you could do the following:

40 +

41 +```bash

42 +npm view ronn@0.3.5 dependencies

43 +```

44 +

45 +You can view child fields by separating them with a period.

46 +To view the git repository URL for the latest version of `npm`, you would run the following command:

47 +

48 +```bash

49 +npm view npm repository.url

50 +```

51 +

52 +This makes it easy to view information about a dependency with a bit of

53 +shell scripting. For example, to view all the data about the version of

54 +`opts` that `ronn` depends on, you could write the following:

55 +

56 +```bash

57 +npm view opts@$(npm view ronn dependencies.opts)

58 +```

59 +

60 +For fields that are arrays, requesting a non-numeric field will return

61 +all of the values from the objects in the list. For example, to get all

62 +the contributor email addresses for the `express` package, you would run:

63 +

64 +```bash

65 +npm view express contributors.email

66 +```

67 +

68 +You may also use numeric indices in square braces to specifically select

69 +an item in an array field. To just get the email address of the first

70 +contributor in the list, you can run:

71 +

72 +```bash

73 +npm view express contributors[0].email

74 +```

75 +

76 +Multiple fields may be specified, and will be printed one after another.

77 +For example, to get all the contributor names and email addresses, you

78 +can do this:

79 +

80 +```bash

81 +npm view express contributors.name contributors.email

82 +```

83 +

84 +"Person" fields are shown as a string if they would be shown as an

85 +object. So, for example, this will show the list of `npm` contributors in

86 +the shortened string format. (See [`package.json`](/cli/v8/configuring-npm/package-json) for more on this.)

87 +

88 +```bash

89 +npm view npm contributors

90 +```

91 +

92 +If a version range is provided, then data will be printed for every

93 +matching version of the package. This will show which version of `jsdom`

94 +was required by each matching version of `yui3`:

95 +

96 +```bash

97 +npm view yui3@'>0.5.4' dependencies.jsdom

98 +```

99 +

100 +To show the `connect` package version history, you can do

101 +this:

102 +

103 +```bash

104 +npm view connect versions

105 +```

106 +

107 +### Configuration

108 +

109 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

110 +<!-- automatically generated, do not edit manually -->

111 +<!-- see lib/utils/config/definitions.js -->

112 +#### `json`

113 +

114 +* Default: false

115 +* Type: Boolean

116 +

117 +Whether or not to output JSON data, rather than the normal output.

118 +

119 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

120 + saving them to your `package.json`.

121 +

122 +Not supported by all npm commands.

123 +

124 +<!-- automatically generated, do not edit manually -->

125 +<!-- see lib/utils/config/definitions.js -->

126 +

127 +#### `workspace`

128 +

129 +* Default:

130 +* Type: String (can be set multiple times)

131 +

132 +Enable running a command in the context of the configured workspaces of the

133 +current project while filtering by running only the workspaces defined by

134 +this configuration option.

135 +

136 +Valid values for the `workspace` config are either:

137 +

138 +* Workspace names

139 +* Path to a workspace directory

140 +* Path to a parent workspace directory (will result in selecting all

141 + workspaces within that folder)

142 +

143 +When set for the `npm init` command, this may be set to the folder of a

144 +workspace which does not yet exist, to create the folder and set it up as a

145 +brand new workspace within the project.

146 +

147 +This value is not exported to the environment for child processes.

148 +

149 +<!-- automatically generated, do not edit manually -->

150 +<!-- see lib/utils/config/definitions.js -->

151 +

152 +#### `workspaces`

153 +

154 +* Default: null

155 +* Type: null or Boolean

156 +

157 +Set to true to run the command in the context of **all** configured

158 +workspaces.

159 +

160 +Explicitly setting this to false will cause commands like `install` to

161 +ignore workspaces altogether. When not set explicitly:

162 +

163 +- Commands that operate on the `node_modules` tree (install, update, etc.)

164 +will link workspaces into the `node_modules` folder. - Commands that do

165 +other things (test, exec, publish, etc.) will operate on the root project,

166 +_unless_ one or more workspaces are specified in the `workspace` config.

167 +

168 +This value is not exported to the environment for child processes.

169 +

170 +<!-- automatically generated, do not edit manually -->

171 +<!-- see lib/utils/config/definitions.js -->

172 +

173 +#### `include-workspace-root`

174 +

175 +* Default: false

176 +* Type: Boolean

177 +

178 +Include the workspace root when workspaces are enabled for a command.

179 +

180 +When false, specifying individual workspaces via the `workspace` config, or

181 +all workspaces via the `workspaces` flag, will cause npm to operate only on

182 +the specified workspaces, and not on the root project.

183 +

184 +<!-- automatically generated, do not edit manually -->

185 +<!-- see lib/utils/config/definitions.js -->

186 +

187 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

188 +

189 +### Output

190 +

191 +If only a single string field for a single version is output, then it

192 +will not be colorized or quoted, to enable piping the output to

193 +another command. If the field is an object, it will be output as a JavaScript object literal.

194 +

195 +If the `--json` flag is given, the outputted fields will be JSON.

196 +

197 +If the version range matches multiple versions then each printed value

198 +will be prefixed with the version it applies to.

199 +

200 +If multiple fields are requested, then each of them is prefixed with

201 +the field name.

202 +

203 +### See Also

204 +

205 +* [npm search](/cli/v8/commands/npm-search)

206 +* [npm registry](/cli/v8/using-npm/registry)

207 +* [npm config](/cli/v8/commands/npm-config)

208 +* [npmrc](/cli/v8/configuring-npm/npmrc)

209 +* [npm docs](/cli/v8/commands/npm-docs)

content/cli/v8/commands/npm-whoami.md new

+57

@@ -0,0 +1,57 @@

1 +---

2 +title: npm-whoami

3 +section: 1

4 +description: Display npm username

5 +redirect_from:

6 + - /cli/whoami

7 + - /cli/whoami.html

8 + - /cli/commands/whoami

9 + - /cli-commands/whoami

10 + - /cli-commands/whoami.html

11 + - /cli-commands/npm-whoami

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/commands/npm-whoami.md

15 +---

16 +

17 +### Synopsis

18 +

19 +```bash

20 +npm whoami [--registry <registry>]

21 +```

22 +

23 +Note: This command is unaware of workspaces.

24 +

25 +### Description

26 +

27 +Display the npm username of the currently logged-in user.

28 +

29 +If logged into a registry that provides token-based authentication, then

30 +connect to the `/-/whoami` registry endpoint to find the username

31 +associated with the token, and print to standard output.

32 +

33 +If logged into a registry that uses Basic Auth, then simply print the

34 +`username` portion of the authentication string.

35 +

36 +### Configuration

37 +

38 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

39 +<!-- automatically generated, do not edit manually -->

40 +<!-- see lib/utils/config/definitions.js -->

41 +#### `registry`

42 +

43 +* Default: "https://registry.npmjs.org/"

44 +* Type: URL

45 +

46 +The base URL of the npm registry.

47 +

48 +<!-- automatically generated, do not edit manually -->

49 +<!-- see lib/utils/config/definitions.js -->

50 +

51 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

52 +

53 +### See Also

54 +

55 +* [npm config](/cli/v8/commands/npm-config)

56 +* [npmrc](/cli/v8/configuring-npm/npmrc)

57 +* [npm adduser](/cli/v8/commands/npm-adduser)

content/cli/v8/commands/npm.md new

+182

@@ -0,0 +1,182 @@

1 +---

2 +title: npm

3 +section: 1

4 +description: javascript package manager

5 +redirect_from:

6 + - /cli/npm

7 + - /cli/npm.html

8 + - /cli/commands/npm

9 + - /cli-commands/npm

10 + - /cli-commands/npm.html

11 +github_repo: npm/cli

12 +github_branch: latest

13 +github_path: docs/content/commands/npm.md

14 +---

15 +

16 +### Synopsis

17 +

18 +```bash

19 +npm <command> [args]

20 +```

21 +

22 +### Version

23 +

24 +8.0.0

25 +

26 +### Description

27 +

28 +npm is the package manager for the Node JavaScript platform. It puts

29 +modules in place so that node can find them, and manages dependency

30 +conflicts intelligently.

31 +

32 +It is extremely configurable to support a variety of use cases. Most

33 +commonly, you use it to publish, discover, install, and develop node

34 +programs.

35 +

36 +Run `npm help` to get a list of available commands.

37 +

38 +### Important

39 +

40 +npm comes preconfigured to use npm's public registry at

41 +https://registry.npmjs.org by default. Use of the npm public registry is

42 +subject to terms of use available at

43 +https://docs.npmjs.com/policies/terms.

44 +

45 +You can configure npm to use any compatible registry you like, and even

46 +run your own registry. Use of someone else's registry is governed by

47 +their terms of use.

48 +

49 +### Introduction

50 +

51 +You probably got npm because you want to install stuff.

52 +

53 +The very first thing you will most likely want to run in any node

54 +program is `npm install` to install its dependencies.

55 +

56 +You can also run `npm install blerg` to install the latest version of

57 +"blerg". Check out [`npm install`](/cli/v8/commands/npm-install) for more

58 +info. It can do a lot of stuff.

59 +

60 +Use the `npm search` command to show everything that's available in the

61 +public registry. Use `npm ls` to show everything you've installed.

62 +

63 +### Dependencies

64 +

65 +If a package lists a dependency using a git URL, npm will install that

66 +dependency using the [`git`](https://github.com/git-guides/install-git)

67 +command and will generate an error if it is not installed.

68 +

69 +If one of the packages npm tries to install is a native node module and

70 +requires compiling of C++ Code, npm will use

71 +[node-gyp](https://github.com/nodejs/node-gyp) for that task.

72 +For a Unix system, [node-gyp](https://github.com/nodejs/node-gyp)

73 +needs Python, make and a buildchain like GCC. On Windows,

74 +Python and Microsoft Visual Studio C++ are needed. For more information

75 +visit [the node-gyp repository](https://github.com/nodejs/node-gyp) and

76 +the [node-gyp Wiki](https://github.com/nodejs/node-gyp/wiki).

77 +

78 +### Directories

79 +

80 +See [`folders`](/cli/v8/configuring-npm/folders) to learn about where npm puts

81 +stuff.

82 +

83 +In particular, npm has two modes of operation:

84 +

85 +* local mode:

86 + npm installs packages into the current project directory, which

87 + defaults to the current working directory. Packages install to

88 + `./node_modules`, and bins to `./node_modules/.bin`.

89 +* global mode:

90 + npm installs packages into the install prefix at

91 + `$npm_config_prefix/lib/node_modules` and bins to

92 + `$npm_config_prefix/bin`.

93 +

94 +Local mode is the default. Use `-g` or `--global` on any command to

95 +run in global mode instead.

96 +

97 +### Developer Usage

98 +

99 +If you're using npm to develop and publish your code, check out the

100 +following help topics:

101 +

102 +* json:

103 + Make a package.json file. See

104 + [`package.json`](/cli/v8/configuring-npm/package-json).

105 +* link:

106 + Links your current working code into Node's path, so that you don't

107 + have to reinstall every time you make a change. Use [`npm

108 + link`](/cli/v8/commands/npm-link) to do this.

109 +* install:

110 + It's a good idea to install things if you don't need the symbolic

111 + link. Especially, installing other peoples code from the registry is

112 + done via [`npm install`](/cli/v8/commands/npm-install)

113 +* adduser:

114 + Create an account or log in. When you do this, npm will store

115 + credentials in the user config file config file.

116 +* publish:

117 + Use the [`npm publish`](/cli/v8/commands/npm-publish) command to upload your

118 + code to the registry.

119 +

120 +#### Configuration

121 +

122 +npm is extremely configurable. It reads its configuration options from

123 +5 places.

124 +

125 +* Command line switches:

126 + Set a config with `--key val`. All keys take a value, even if they

127 + are booleans (the config parser doesn't know what the options are at

128 + the time of parsing). If you do not provide a value (`--key`) then

129 + the option is set to boolean `true`.

130 +* Environment Variables:

131 + Set any config by prefixing the name in an environment variable with

132 + `npm_config_`. For example, `export npm_config_key=val`.

133 +* User Configs:

134 + The file at `$HOME/.npmrc` is an ini-formatted list of configs. If

135 + present, it is parsed. If the `userconfig` option is set in the cli

136 + or env, that file will be used instead.

137 +* Global Configs:

138 + The file found at `./etc/npmrc` (relative to the global prefix will be

139 + parsed if it is found. See [`npm prefix`](/cli/v8/commands/npm-prefix) for

140 + more info on the global prefix. If the `globalconfig` option is set

141 + in the cli, env, or user config, then that file is parsed instead.

142 +* Defaults:

143 + npm's default configuration options are defined in

144 + lib/utils/config-defs.js. These must not be changed.

145 +

146 +See [`config`](/cli/v8/using-npm/config) for much much more information.

147 +

148 +### Contributions

149 +

150 +Patches welcome!

151 +

152 +If you would like to help, but don't know what to work on, read the

153 +[contributing

154 +guidelines](https://github.com/npm/cli/blob/latest/CONTRIBUTING.md) and

155 +check the issues list.

156 +

157 +### Bugs

158 +

159 +When you find issues, please report them:

160 +<https://github.com/npm/cli/issues>

161 +

162 +Please be sure to follow the template and bug reporting guidelines.

163 +

164 +### Feature Requests

165 +

166 +Discuss new feature ideas on our discussion forum:

167 +

168 +* <https://github.com/npm/feedback>

169 +

170 +Or suggest formal RFC proposals:

171 +

172 +* <https://github.com/npm/rfcs>

173 +

174 +### See Also

175 +

176 +* [npm help](/cli/v8/commands/npm-help)

177 +* [package.json](/cli/v8/configuring-npm/package-json)

178 +* [npmrc](/cli/v8/configuring-npm/npmrc)

179 +* [npm config](/cli/v8/commands/npm-config)

180 +* [npm install](/cli/v8/commands/npm-install)

181 +* [npm prefix](/cli/v8/commands/npm-prefix)

182 +* [npm publish](/cli/v8/commands/npm-publish)

content/cli/v8/commands/npx.md new

+180

@@ -0,0 +1,180 @@

1 +---

2 +title: npx

3 +section: 1

4 +description: Run a command from a local or remote npm package

5 +github_repo: npm/cli

6 +github_branch: latest

7 +github_path: docs/content/commands/npx.md

8 +---

9 +

10 +### Synopsis

11 +

12 +```bash

13 +npm exec -- <pkg>[@<version>] [args...]

14 +npm exec --package=<pkg>[@<version>] -- <cmd> [args...]

15 +npm exec -c '<cmd> [args...]'

16 +npm exec --package=foo -c '<cmd> [args...]'

17 +

18 +npx <pkg>[@<specifier>] [args...]

19 +npx -p <pkg>[@<specifier>] <cmd> [args...]

20 +npx -c '<cmd> [args...]'

21 +npx -p <pkg>[@<specifier>] -c '<cmd> [args...]'

22 +

23 +alias: npm x, npx

24 +

25 +--package=<pkg> (may be specified multiple times)

26 +-p is a shorthand for --package only when using npx executable

27 +-c <cmd> --call=<cmd> (may not be mixed with positional arguments)

28 +```

29 +

30 +### Description

31 +

32 +This command allows you to run an arbitrary command from an npm package

33 +(either one installed locally, or fetched remotely), in a similar context

34 +as running it via `npm run`.

35 +

36 +Whatever packages are specified by the `--package` option will be

37 +provided in the `PATH` of the executed command, along with any locally

38 +installed package executables. The `--package` option may be

39 +specified multiple times, to execute the supplied command in an environment

40 +where all specified packages are available.

41 +

42 +If any requested packages are not present in the local project

43 +dependencies, then they are installed to a folder in the npm cache, which

44 +is added to the `PATH` environment variable in the executed process. A

45 +prompt is printed (which can be suppressed by providing either `--yes` or

46 +`--no`).

47 +

48 +Package names provided without a specifier will be matched with whatever

49 +version exists in the local project. Package names with a specifier will

50 +only be considered a match if they have the exact same name and version as

51 +the local dependency.

52 +

53 +If no `-c` or `--call` option is provided, then the positional arguments

54 +are used to generate the command string. If no `--package` options

55 +are provided, then npm will attempt to determine the executable name from

56 +the package specifier provided as the first positional argument according

57 +to the following heuristic:

58 +

59 +- If the package has a single entry in its `bin` field in `package.json`,

60 + or if all entries are aliases of the same command, then that command

61 + will be used.

62 +- If the package has multiple `bin` entries, and one of them matches the

63 + unscoped portion of the `name` field, then that command will be used.

64 +- If this does not result in exactly one option (either because there are

65 + no bin entries, or none of them match the `name` of the package), then

66 + `npm exec` exits with an error.

67 +

68 +To run a binary _other than_ the named binary, specify one or more

69 +`--package` options, which will prevent npm from inferring the package from

70 +the first command argument.

71 +

72 +### `npx` vs `npm exec`

73 +

74 +When run via the `npx` binary, all flags and options *must* be set prior to

75 +any positional arguments. When run via `npm exec`, a double-hyphen `--`

76 +flag can be used to suppress npm's parsing of switches and options that

77 +should be sent to the executed command.

78 +

79 +For example:

80 +

81 +```

82 +$ npx foo@latest bar --package=@npmcli/foo

83 +```

84 +

85 +In this case, npm will resolve the `foo` package name, and run the

86 +following command:

87 +

88 +```

89 +$ foo bar --package=@npmcli/foo

90 +```

91 +

92 +Since the `--package` option comes _after_ the positional arguments, it is

93 +treated as an argument to the executed command.

94 +

95 +In contrast, due to npm's argument parsing logic, running this command is

96 +different:

97 +

98 +```

99 +$ npm exec foo@latest bar --package=@npmcli/foo

100 +```

101 +

102 +In this case, npm will parse the `--package` option first, resolving the

103 +`@npmcli/foo` package. Then, it will execute the following command in that

104 +context:

105 +

106 +```

107 +$ foo@latest bar

108 +```

109 +

110 +The double-hyphen character is recommended to explicitly tell npm to stop

111 +parsing command line options and switches. The following command would

112 +thus be equivalent to the `npx` command above:

113 +

114 +```

115 +$ npm exec -- foo@latest bar --package=@npmcli/foo

116 +```

117 +

118 +### Examples

119 +

120 +Run the version of `tap` in the local dependencies, with the provided

121 +arguments:

122 +

123 +```

124 +$ npm exec -- tap --bail test/foo.js

125 +$ npx tap --bail test/foo.js

126 +```

127 +

128 +Run a command _other than_ the command whose name matches the package name

129 +by specifying a `--package` option:

130 +

131 +```

132 +$ npm exec --package=foo -- bar --bar-argument

133 +# ~ or ~

134 +$ npx --package=foo bar --bar-argument

135 +```

136 +

137 +Run an arbitrary shell script, in the context of the current project:

138 +

139 +```

140 +$ npm x -c 'eslint && say "hooray, lint passed"'

141 +$ npx -c 'eslint && say "hooray, lint passed"'

142 +```

143 +

144 +### Compatibility with Older npx Versions

145 +

146 +The `npx` binary was rewritten in npm v7.0.0, and the standalone `npx`

147 +package deprecated at that time. `npx` uses the `npm exec`

148 +command instead of a separate argument parser and install process, with

149 +some affordances to maintain backwards compatibility with the arguments it

150 +accepted in previous versions.

151 +

152 +This resulted in some shifts in its functionality:

153 +

154 +- Any `npm` config value may be provided.

155 +- To prevent security and user-experience problems from mistyping package

156 + names, `npx` prompts before installing anything. Suppress this

157 + prompt with the `-y` or `--yes` option.

158 +- The `--no-install` option is deprecated, and will be converted to `--no`.

159 +- Shell fallback functionality is removed, as it is not advisable.

160 +- The `-p` argument is a shorthand for `--parseable` in npm, but shorthand

161 + for `--package` in npx. This is maintained, but only for the `npx`

162 + executable.

163 +- The `--ignore-existing` option is removed. Locally installed bins are

164 + always present in the executed process `PATH`.

165 +- The `--npm` option is removed. `npx` will always use the `npm` it ships

166 + with.

167 +- The `--node-arg` and `-n` options are removed.

168 +- The `--always-spawn` option is redundant, and thus removed.

169 +- The `--shell` option is replaced with `--script-shell`, but maintained

170 + in the `npx` executable for backwards compatibility.

171 +

172 +### See Also

173 +

174 +* [npm run-script](/cli/v8/commands/npm-run-script)

175 +* [npm scripts](/cli/v8/using-npm/scripts)

176 +* [npm test](/cli/v8/commands/npm-test)

177 +* [npm start](/cli/v8/commands/npm-start)

178 +* [npm restart](/cli/v8/commands/npm-restart)

179 +* [npm stop](/cli/v8/commands/npm-stop)

180 +* [npm config](/cli/v8/commands/npm-config)

content/cli/v8/configuring-npm/folders.md new

+229

@@ -0,0 +1,229 @@

1 +---

2 +title: folders

3 +section: 5

4 +description: Folder Structures Used by npm

5 +redirect_from:

6 + - /configuring-npm/folders

7 + - /configuring-npm/folders.html

8 + - /files/folders

9 + - /files/folders.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/configuring-npm/folders.md

13 +---

14 +

15 +### Description

16 +

17 +npm puts various things on your computer. That's its job.

18 +

19 +This document will tell you what it puts where.

20 +

21 +#### tl;dr

22 +

23 +* Local install (default): puts stuff in `./node_modules` of the current

24 + package root.

25 +* Global install (with `-g`): puts stuff in /usr/local or wherever node

26 + is installed.

27 +* Install it **locally** if you're going to `require()` it.

28 +* Install it **globally** if you're going to run it on the command line.

29 +* If you need both, then install it in both places, or use `npm link`.

30 +

31 +#### prefix Configuration

32 +

33 +The `prefix` config defaults to the location where node is installed.

34 +On most systems, this is `/usr/local`. On Windows, it's `%AppData%\npm`.

35 +On Unix systems, it's one level up, since node is typically installed at

36 +`{prefix}/bin/node` rather than `{prefix}/node.exe`.

37 +

38 +When the `global` flag is set, npm installs things into this prefix.

39 +When it is not set, it uses the root of the current package, or the

40 +current working directory if not in a package already.

41 +

42 +#### Node Modules

43 +

44 +Packages are dropped into the `node_modules` folder under the `prefix`.

45 +When installing locally, this means that you can

46 +`require("packagename")` to load its main module, or

47 +`require("packagename/lib/path/to/sub/module")` to load other modules.

48 +

49 +Global installs on Unix systems go to `{prefix}/lib/node_modules`.

50 +Global installs on Windows go to `{prefix}/node_modules` (that is, no

51 +`lib` folder.)

52 +

53 +Scoped packages are installed the same way, except they are grouped together

54 +in a sub-folder of the relevant `node_modules` folder with the name of that

55 +scope prefix by the @ symbol, e.g. `npm install @myorg/package` would place

56 +the package in `{prefix}/node_modules/@myorg/package`. See

57 +[`scope`](/cli/v8/using-npm/scope) for more details.

58 +

59 +If you wish to `require()` a package, then install it locally.

60 +

61 +#### Executables

62 +

63 +When in global mode, executables are linked into `{prefix}/bin` on Unix,

64 +or directly into `{prefix}` on Windows. Ensure that path is in your

65 +terminal's `PATH` environment to run them.

66 +

67 +When in local mode, executables are linked into

68 +`./node_modules/.bin` so that they can be made available to scripts run

69 +through npm. (For example, so that a test runner will be in the path

70 +when you run `npm test`.)

71 +

72 +#### Man Pages

73 +

74 +When in global mode, man pages are linked into `{prefix}/share/man`.

75 +

76 +When in local mode, man pages are not installed.

77 +

78 +Man pages are not installed on Windows systems.

79 +

80 +#### Cache

81 +

82 +See [`npm cache`](/cli/v8/commands/npm-cache). Cache files are stored in `~/.npm` on Posix, or

83 +`%AppData%/npm-cache` on Windows.

84 +

85 +This is controlled by the `cache` configuration param.

86 +

87 +#### Temp Files

88 +

89 +Temporary files are stored by default in the folder specified by the

90 +`tmp` config, which defaults to the TMPDIR, TMP, or TEMP environment

91 +variables, or `/tmp` on Unix and `c:\windows\temp` on Windows.

92 +

93 +Temp files are given a unique folder under this root for each run of the

94 +program, and are deleted upon successful exit.

95 +

96 +### More Information

97 +

98 +When installing locally, npm first tries to find an appropriate

99 +`prefix` folder. This is so that `npm install foo@1.2.3` will install

100 +to the sensible root of your package, even if you happen to have `cd`ed

101 +into some other folder.

102 +

103 +Starting at the $PWD, npm will walk up the folder tree checking for a

104 +folder that contains either a `package.json` file, or a `node_modules`

105 +folder. If such a thing is found, then that is treated as the effective

106 +"current directory" for the purpose of running npm commands. (This

107 +behavior is inspired by and similar to git's .git-folder seeking

108 +logic when running git commands in a working dir.)

109 +

110 +If no package root is found, then the current folder is used.

111 +

112 +When you run `npm install foo@1.2.3`, then the package is loaded into

113 +the cache, and then unpacked into `./node_modules/foo`. Then, any of

114 +foo's dependencies are similarly unpacked into

115 +`./node_modules/foo/node_modules/...`.

116 +

117 +Any bin files are symlinked to `./node_modules/.bin/`, so that they may

118 +be found by npm scripts when necessary.

119 +

120 +#### Global Installation

121 +

122 +If the `global` configuration is set to true, then npm will

123 +install packages "globally".

124 +

125 +For global installation, packages are installed roughly the same way,

126 +but using the folders described above.

127 +

128 +#### Cycles, Conflicts, and Folder Parsimony

129 +

130 +Cycles are handled using the property of node's module system that it

131 +walks up the directories looking for `node_modules` folders. So, at every

132 +stage, if a package is already installed in an ancestor `node_modules`

133 +folder, then it is not installed at the current location.

134 +

135 +Consider the case above, where `foo -> bar -> baz`. Imagine if, in

136 +addition to that, baz depended on bar, so you'd have:

137 +`foo -> bar -> baz -> bar -> baz ...`. However, since the folder

138 +structure is: `foo/node_modules/bar/node_modules/baz`, there's no need to

139 +put another copy of bar into `.../baz/node_modules`, since when it calls

140 +require("bar"), it will get the copy that is installed in

141 +`foo/node_modules/bar`.

142 +

143 +This shortcut is only used if the exact same

144 +version would be installed in multiple nested `node_modules` folders. It

145 +is still possible to have `a/node_modules/b/node_modules/a` if the two

146 +"a" packages are different versions. However, without repeating the

147 +exact same package multiple times, an infinite regress will always be

148 +prevented.

149 +

150 +Another optimization can be made by installing dependencies at the

151 +highest level possible, below the localized "target" folder.

152 +

153 +#### Example

154 +

155 +Consider this dependency graph:

156 +

157 +```bash

158 +foo

159 ++-- blerg@1.2.5

160 ++-- bar@1.2.3

161 +| +-- blerg@1.x (latest=1.3.7)

162 +| +-- baz@2.x

163 +| | `-- quux@3.x

164 +| | `-- bar@1.2.3 (cycle)

165 +| `-- asdf@*

166 +`-- baz@1.2.3

167 + `-- quux@3.x

168 + `-- bar

169 +```

170 +

171 +In this case, we might expect a folder structure like this:

172 +

173 +```bash

174 +foo

175 ++-- node_modules

176 + +-- blerg (1.2.5) <---[A]

177 + +-- bar (1.2.3) <---[B]

178 + | `-- node_modules

179 + | +-- baz (2.0.2) <---[C]

180 + | | `-- node_modules

181 + | | `-- quux (3.2.0)

182 + | `-- asdf (2.3.4)

183 + `-- baz (1.2.3) <---[D]

184 + `-- node_modules

185 + `-- quux (3.2.0) <---[E]

186 +```

187 +

188 +Since foo depends directly on `bar@1.2.3` and `baz@1.2.3`, those are

189 +installed in foo's `node_modules` folder.

190 +

191 +Even though the latest copy of blerg is 1.3.7, foo has a specific

192 +dependency on version 1.2.5. So, that gets installed at [A]. Since the

193 +parent installation of blerg satisfies bar's dependency on `blerg@1.x`,

194 +it does not install another copy under [B].

195 +

196 +Bar [B] also has dependencies on baz and asdf, so those are installed in

197 +bar's `node_modules` folder. Because it depends on `baz@2.x`, it cannot

198 +re-use the `baz@1.2.3` installed in the parent `node_modules` folder [D],

199 +and must install its own copy [C].

200 +

201 +Underneath bar, the `baz -> quux -> bar` dependency creates a cycle.

202 +However, because bar is already in quux's ancestry [B], it does not

203 +unpack another copy of bar into that folder.

204 +

205 +Underneath `foo -> baz` [D], quux's [E] folder tree is empty, because its

206 +dependency on bar is satisfied by the parent folder copy installed at [B].

207 +

208 +For a graphical breakdown of what is installed where, use `npm ls`.

209 +

210 +#### Publishing

211 +

212 +Upon publishing, npm will look in the `node_modules` folder. If any of

213 +the items there are not in the `bundledDependencies` array, then they will

214 +not be included in the package tarball.

215 +

216 +This allows a package maintainer to install all of their dependencies

217 +(and dev dependencies) locally, but only re-publish those items that

218 +cannot be found elsewhere. See [`package.json`](/cli/v8/configuring-npm/package-json) for more information.

219 +

220 +### See also

221 +

222 +* [package.json](/cli/v8/configuring-npm/package-json)

223 +* [npm install](/cli/v8/commands/npm-install)

224 +* [npm pack](/cli/v8/commands/npm-pack)

225 +* [npm cache](/cli/v8/commands/npm-cache)

226 +* [npm config](/cli/v8/commands/npm-config)

227 +* [npmrc](/cli/v8/configuring-npm/npmrc)

228 +* [config](/cli/v8/using-npm/config)

229 +* [npm publish](/cli/v8/commands/npm-publish)

content/cli/v8/configuring-npm/index.mdx new

+12

@@ -0,0 +1,12 @@

1 +---

2 +redirect_from:

3 + - configuring-npm

4 + - /cli/configuring-npm

5 + - /cli-documentation/configuring-npm

6 + - /cli-documentation/files

7 +github_repo: npm/cli

8 +github_branch: latest

9 +github_path: docs/content/configuring-npm/index.mdx

10 +title: Configuring npm

11 +---

12 +<Index depth="1" />

\ No newline at end of file

content/cli/v8/configuring-npm/install.md new

+93

@@ -0,0 +1,93 @@

1 +---

2 +title: install

3 +section: 5

4 +description: Download and install node and npm

5 +redirect_from:

6 + - /configuring-npm/install

7 + - /configuring-npm/install.html

8 +github_repo: npm/cli

9 +github_branch: latest

10 +github_path: docs/content/configuring-npm/install.md

11 +---

12 +

13 +### Description

14 +

15 +To publish and install packages to and from the public npm registry, you

16 +must install Node.js and the npm command line interface using either a Node

17 +version manager or a Node installer. **We strongly recommend using a Node

18 +version manager to install Node.js and npm.** We do not recommend using a

19 +Node installer, since the Node installation process installs npm in a

20 +directory with local permissions and can cause permissions errors when you

21 +run npm packages globally.

22 +

23 +### Overview

24 +

25 +- [Checking your version of npm and

26 + Node.js](#checking-your-version-of-npm-and-node-js)

27 +- [Using a Node version manager to install Node.js and

28 + npm](#using-a-node-version-manager-to-install-node-js-and-npm)

29 +- [Using a Node installer to install Node.js and

30 + npm](#using-a-node-installer-to-install-node-js-and-npm)

31 +

32 +### Checking your version of npm and Node.js

33 +

34 +To see if you already have Node.js and npm installed and check the

35 +installed version, run the following commands:

36 +

37 +```

38 +node -v

39 +npm -v

40 +```

41 +

42 +### Using a Node version manager to install Node.js and npm

43 +

44 +Node version managers allow you to install and switch between multiple

45 +versions of Node.js and npm on your system so you can test your

46 +applications on multiple versions of npm to ensure they work for users on

47 +different versions.

48 +

49 +#### OSX or Linux Node version managers

50 +

51 +* [nvm](https://github.com/creationix/nvm)

52 +* [n](https://github.com/tj/n)

53 +

54 +#### Windows Node version managers

55 +

56 +* [nodist](https://github.com/marcelklehr/nodist)

57 +* [nvm-windows](https://github.com/coreybutler/nvm-windows)

58 +

59 +### Using a Node installer to install Node.js and npm

60 +

61 +If you are unable to use a Node version manager, you can use a Node

62 +installer to install both Node.js and npm on your system.

63 +

64 +* [Node.js installer](https://nodejs.org/en/download/)

65 +* [NodeSource installer](https://github.com/nodesource/distributions). If

66 + you use Linux, we recommend that you use a NodeSource installer.

67 +

68 +#### OS X or Windows Node installers

69 +

70 +If you're using OS X or Windows, use one of the installers from the

71 +[Node.js download page](https://nodejs.org/en/download/). Be sure to

72 +install the version labeled **LTS**. Other versions have not yet been

73 +tested with npm.

74 +

75 +#### Linux or other operating systems Node installers

76 +

77 +If you're using Linux or another operating system, use one of the following

78 +installers:

79 +

80 +- [NodeSource installer](https://github.com/nodesource/distributions)

81 + (recommended)

82 +- One of the installers on the [Node.js download

83 + page](https://nodejs.org/en/download/)

84 +

85 +Or see [this page](https://nodejs.org/en/download/package-manager/) to

86 +install npm for Linux in the way many Linux developers prefer.

87 +

88 +#### Less-common operating systems

89 +

90 +For more information on installing Node.js on a variety of operating

91 +systems, see [this page][pkg-mgr].

92 +

93 +[pkg-mgr]: https://nodejs.org/en/download/package-manager/

content/cli/v8/configuring-npm/npm-shrinkwrap-json.md new

+40

@@ -0,0 +1,40 @@

1 +---

2 +title: npm-shrinkwrap.json

3 +section: 5

4 +description: A publishable lockfile

5 +redirect_from:

6 + - /configuring-npm/npm-shrinkwrap-json

7 + - /configuring-npm/npm-shrinkwrap-json.html

8 +github_repo: npm/cli

9 +github_branch: latest

10 +github_path: docs/content/configuring-npm/npm-shrinkwrap-json.md

11 +---

12 +

13 +### Description

14 +

15 +`npm-shrinkwrap.json` is a file created by [`npm

16 +shrinkwrap`](/cli/v8/commands/npm-shrinkwrap). It is identical to

17 +`package-lock.json`, with one major caveat: Unlike `package-lock.json`,

18 +`npm-shrinkwrap.json` may be included when publishing a package.

19 +

20 +The recommended use-case for `npm-shrinkwrap.json` is applications deployed

21 +through the publishing process on the registry: for example, daemons and

22 +command-line tools intended as global installs or `devDependencies`. It's

23 +strongly discouraged for library authors to publish this file, since that

24 +would prevent end users from having control over transitive dependency

25 +updates.

26 +

27 +If both `package-lock.json` and `npm-shrinkwrap.json` are present in a

28 +package root, `npm-shrinkwrap.json` will be preferred over the

29 +`package-lock.json` file.

30 +

31 +For full details and description of the `npm-shrinkwrap.json` file format,

32 +refer to the manual page for

33 +[package-lock.json](/cli/v8/configuring-npm/package-lock-json).

34 +

35 +### See also

36 +

37 +* [npm shrinkwrap](/cli/v8/commands/npm-shrinkwrap)

38 +* [package-lock.json](/cli/v8/configuring-npm/package-lock-json)

39 +* [package.json](/cli/v8/configuring-npm/package-json)

40 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/configuring-npm/npmrc.md new

+109

@@ -0,0 +1,109 @@

1 +---

2 +title: npmrc

3 +section: 5

4 +description: The npm config files

5 +redirect_from:

6 + - /configuring-npm/npmrc

7 + - /configuring-npm/npmrc.html

8 + - /cli-documentation/files/npmrc

9 + - /files/npmrc

10 + - /files/npmrc.html

11 +github_repo: npm/cli

12 +github_branch: latest

13 +github_path: docs/content/configuring-npm/npmrc.md

14 +---

15 +

16 +### Description

17 +

18 +npm gets its config settings from the command line, environment variables,

19 +and `npmrc` files.

20 +

21 +The `npm config` command can be used to update and edit the contents of the

22 +user and global npmrc files.

23 +

24 +For a list of available configuration options, see

25 +[config](/cli/v8/using-npm/config).

26 +

27 +### Files

28 +

29 +The four relevant files are:

30 +

31 +* per-project config file (/path/to/my/project/.npmrc)

32 +* per-user config file (~/.npmrc)

33 +* global config file ($PREFIX/etc/npmrc)

34 +* npm builtin config file (/path/to/npm/npmrc)

35 +

36 +All npm config files are an ini-formatted list of `key = value` parameters.

37 +Environment variables can be replaced using `${VARIABLE_NAME}`. For

38 +example:

39 +

40 +```bash

41 +prefix = ${HOME}/.npm-packages

42 +```

43 +

44 +Each of these files is loaded, and config options are resolved in priority

45 +order. For example, a setting in the userconfig file would override the

46 +setting in the globalconfig file.

47 +

48 +Array values are specified by adding "[]" after the key name. For example:

49 +

50 +```bash

51 +key[] = "first value"

52 +key[] = "second value"

53 +```

54 +

55 +#### Comments

56 +

57 +Lines in `.npmrc` files are interpreted as comments when they begin with a

58 +`;` or `#` character. `.npmrc` files are parsed by

59 +[npm/ini](https://github.com/npm/ini), which specifies this comment syntax.

60 +

61 +For example:

62 +

63 +```bash

64 +# last modified: 01 Jan 2016

65 +; Set a new registry for a scoped package

66 +@myscope:registry=https://mycustomregistry.example.org

67 +```

68 +

69 +#### Per-project config file

70 +

71 +When working locally in a project, a `.npmrc` file in the root of the

72 +project (ie, a sibling of `node_modules` and `package.json`) will set

73 +config values specific to this project.

74 +

75 +Note that this only applies to the root of the project that you're running

76 +npm in. It has no effect when your module is published. For example, you

77 +can't publish a module that forces itself to install globally, or in a

78 +different location.

79 +

80 +Additionally, this file is not read in global mode, such as when running

81 +`npm install -g`.

82 +

83 +#### Per-user config file

84 +

85 +`$HOME/.npmrc` (or the `userconfig` param, if set in the environment or on

86 +the command line)

87 +

88 +#### Global config file

89 +

90 +`$PREFIX/etc/npmrc` (or the `globalconfig` param, if set above): This file

91 +is an ini-file formatted list of `key = value` parameters. Environment

92 +variables can be replaced as above.

93 +

94 +#### Built-in config file

95 +

96 +`path/to/npm/itself/npmrc`

97 +

98 +This is an unchangeable "builtin" configuration file that npm keeps

99 +consistent across updates. Set fields in here using the `./configure`

100 +script that comes with npm. This is primarily for distribution maintainers

101 +to override default configs in a standard and consistent manner.

102 +

103 +### See also

104 +

105 +* [npm folders](/cli/v8/configuring-npm/folders)

106 +* [npm config](/cli/v8/commands/npm-config)

107 +* [config](/cli/v8/using-npm/config)

108 +* [package.json](/cli/v8/configuring-npm/package-json)

109 +* [npm](/cli/v8/commands/npm)

content/cli/v8/configuring-npm/package-json.md new

+1049

@@ -0,0 +1,1049 @@

1 +---

2 +title: package.json

3 +section: 5

4 +description: Specifics of npm's package.json handling

5 +redirect_from:

6 + - /configuring-npm/package-json

7 + - /configuring-npm/package-json.html

8 + - /configuring-npm/package.json

9 + - /creating-a-packge-json-file

10 + - /files/package.json

11 + - /files/package.json.html

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/configuring-npm/package-json.md

15 +---

16 +

17 +### Description

18 +

19 +This document is all you need to know about what's required in your

20 +package.json file. It must be actual JSON, not just a JavaScript object

21 +literal.

22 +

23 +A lot of the behavior described in this document is affected by the config

24 +settings described in [`config`](/cli/v8/using-npm/config).

25 +

26 +### name

27 +

28 +If you plan to publish your package, the *most* important things in your

29 +package.json are the name and version fields as they will be required. The

30 +name and version together form an identifier that is assumed to be

31 +completely unique. Changes to the package should come along with changes

32 +to the version. If you don't plan to publish your package, the name and

33 +version fields are optional.

34 +

35 +The name is what your thing is called.

36 +

37 +Some rules:

38 +

39 +* The name must be less than or equal to 214 characters. This includes the

40 + scope for scoped packages.

41 +* The names of scoped packages can begin with a dot or an underscore. This

42 + is not permitted without a scope.

43 +* New packages must not have uppercase letters in the name.

44 +* The name ends up being part of a URL, an argument on the command line,

45 + and a folder name. Therefore, the name can't contain any non-URL-safe

46 + characters.

47 +

48 +Some tips:

49 +

50 +* Don't use the same name as a core Node module.

51 +* Don't put "js" or "node" in the name. It's assumed that it's js, since

52 + you're writing a package.json file, and you can specify the engine using

53 + the "engines" field. (See below.)

54 +* The name will probably be passed as an argument to require(), so it

55 + should be something short, but also reasonably descriptive.

56 +* You may want to check the npm registry to see if there's something by

57 + that name already, before you get too attached to it.

58 + <https://www.npmjs.com/>

59 +

60 +A name can be optionally prefixed by a scope, e.g. `@myorg/mypackage`. See

61 +[`scope`](/cli/v8/using-npm/scope) for more detail.

62 +

63 +### version

64 +

65 +If you plan to publish your package, the *most* important things in your

66 +package.json are the name and version fields as they will be required. The

67 +name and version together form an identifier that is assumed to be

68 +completely unique. Changes to the package should come along with changes

69 +to the version. If you don't plan to publish your package, the name and

70 +version fields are optional.

71 +

72 +Version must be parseable by

73 +[node-semver](https://github.com/npm/node-semver), which is bundled with

74 +npm as a dependency. (`npm install semver` to use it yourself.)

75 +

76 +### description

77 +

78 +Put a description in it. It's a string. This helps people discover your

79 +package, as it's listed in `npm search`.

80 +

81 +### keywords

82 +

83 +Put keywords in it. It's an array of strings. This helps people discover

84 +your package as it's listed in `npm search`.

85 +

86 +### homepage

87 +

88 +The url to the project homepage.

89 +

90 +Example:

91 +

92 +```json

93 +"homepage": "https://github.com/owner/project#readme"

94 +```

95 +

96 +### bugs

97 +

98 +The url to your project's issue tracker and / or the email address to which

99 +issues should be reported. These are helpful for people who encounter

100 +issues with your package.

101 +

102 +It should look like this:

103 +

104 +```json

105 +{

106 + "url" : "https://github.com/owner/project/issues",

107 + "email" : "project@hostname.com"

108 +}

109 +```

110 +

111 +You can specify either one or both values. If you want to provide only a

112 +url, you can specify the value for "bugs" as a simple string instead of an

113 +object.

114 +

115 +If a url is provided, it will be used by the `npm bugs` command.

116 +

117 +### license

118 +

119 +You should specify a license for your package so that people know how they

120 +are permitted to use it, and any restrictions you're placing on it.

121 +

122 +If you're using a common license such as BSD-2-Clause or MIT, add a current

123 +SPDX license identifier for the license you're using, like this:

124 +

125 +```json

126 +{

127 + "license" : "BSD-3-Clause"

128 +}

129 +```

130 +

131 +You can check [the full list of SPDX license

132 +IDs](https://spdx.org/licenses/). Ideally you should pick one that is

133 +[OSI](https://opensource.org/licenses/alphabetical) approved.

134 +

135 +If your package is licensed under multiple common licenses, use an [SPDX

136 +license expression syntax version 2.0

137 +string](https://www.npmjs.com/package/spdx), like this:

138 +

139 +```json

140 +{

141 + "license" : "(ISC OR GPL-3.0)"

142 +}

143 +```

144 +If you are using a license that hasn't been assigned an SPDX identifier, or if

145 +you are using a custom license, use a string value like this one:

146 +

147 +```json

148 +{

149 + "license" : "SEE LICENSE IN <filename>"

150 +}

151 +```

152 +Then include a file named `<filename>` at the top level of the package.

153 +

154 +Some old packages used license objects or a "licenses" property containing

155 +an array of license objects:

156 +

157 +```json

158 +// Not valid metadata

159 +{

160 + "license" : {

161 + "type" : "ISC",

162 + "url" : "https://opensource.org/licenses/ISC"

163 + }

164 +}

165 +

166 +// Not valid metadata

167 +{

168 + "licenses" : [

169 + {

170 + "type": "MIT",

171 + "url": "https://www.opensource.org/licenses/mit-license.php"

172 + },

173 + {

174 + "type": "Apache-2.0",

175 + "url": "https://opensource.org/licenses/apache2.0.php"

176 + }

177 + ]

178 +}

179 +```

180 +

181 +Those styles are now deprecated. Instead, use SPDX expressions, like this:

182 +

183 +```json

184 +{

185 + "license": "ISC"

186 +}

187 +```

188 +

189 +```json

190 +{

191 + "license": "(MIT OR Apache-2.0)"

192 +}

193 +```

194 +

195 +Finally, if you do not wish to grant others the right to use a private or

196 +unpublished package under any terms:

197 +

198 +```json

199 +{

200 + "license": "UNLICENSED"

201 +}

202 +```

203 +

204 +Consider also setting `"private": true` to prevent accidental publication.

205 +

206 +### people fields: author, contributors

207 +

208 +The "author" is one person. "contributors" is an array of people. A

209 +"person" is an object with a "name" field and optionally "url" and "email",

210 +like this:

211 +

212 +```json

213 +{

214 + "name" : "Barney Rubble",

215 + "email" : "b@rubble.com",

216 + "url" : "http://barnyrubble.tumblr.com/"

217 +}

218 +```

219 +

220 +Or you can shorten that all into a single string, and npm will parse it for

221 +you:

222 +

223 +```json

224 +{

225 + "author": "Barney Rubble <b@rubble.com> (http://barnyrubble.tumblr.com/)"

226 +}

227 +```

228 +

229 +Both email and url are optional either way.

230 +

231 +npm also sets a top-level "maintainers" field with your npm user info.

232 +

233 +### funding

234 +

235 +You can specify an object containing an URL that provides up-to-date

236 +information about ways to help fund development of your package, or a

237 +string URL, or an array of these:

238 +

239 +```json

240 +{

241 + "funding": {

242 + "type" : "individual",

243 + "url" : "http://example.com/donate"

244 + },

245 +

246 + "funding": {

247 + "type" : "patreon",

248 + "url" : "https://www.patreon.com/my-account"

249 + },

250 +

251 + "funding": "http://example.com/donate",

252 +

253 + "funding": [

254 + {

255 + "type" : "individual",

256 + "url" : "http://example.com/donate"

257 + },

258 + "http://example.com/donateAlso",

259 + {

260 + "type" : "patreon",

261 + "url" : "https://www.patreon.com/my-account"

262 + }

263 + ]

264 +}

265 +```

266 +

267 +Users can use the `npm fund` subcommand to list the `funding` URLs of all

268 +dependencies of their project, direct and indirect. A shortcut to visit

269 +each funding url is also available when providing the project name such as:

270 +`npm fund <projectname>` (when there are multiple URLs, the first one will

271 +be visited)

272 +

273 +### files

274 +

275 +The optional `files` field is an array of file patterns that describes the

276 +entries to be included when your package is installed as a dependency. File

277 +patterns follow a similar syntax to `.gitignore`, but reversed: including a

278 +file, directory, or glob pattern (`*`, `**/*`, and such) will make it so

279 +that file is included in the tarball when it's packed. Omitting the field

280 +will make it default to `["*"]`, which means it will include all files.

281 +

282 +Some special files and directories are also included or excluded regardless

283 +of whether they exist in the `files` array (see below).

284 +

285 +You can also provide a `.npmignore` file in the root of your package or in

286 +subdirectories, which will keep files from being included. At the root of

287 +your package it will not override the "files" field, but in subdirectories

288 +it will. The `.npmignore` file works just like a `.gitignore`. If there is

289 +a `.gitignore` file, and `.npmignore` is missing, `.gitignore`'s contents

290 +will be used instead.

291 +

292 +Files included with the "package.json#files" field _cannot_ be excluded

293 +through `.npmignore` or `.gitignore`.

294 +

295 +Certain files are always included, regardless of settings:

296 +

297 +* `package.json`

298 +* `README`

299 +* `LICENSE` / `LICENCE`

300 +* The file in the "main" field

301 +

302 +`README` & `LICENSE` can have any case and extension.

303 +

304 +Conversely, some files are always ignored:

305 +

306 +* `.git`

307 +* `CVS`

308 +* `.svn`

309 +* `.hg`

310 +* `.lock-wscript`

311 +* `.wafpickle-N`

312 +* `.*.swp`

313 +* `.DS_Store`

314 +* `._*`

315 +* `npm-debug.log`

316 +* `.npmrc`

317 +* `node_modules`

318 +* `config.gypi`

319 +* `*.orig`

320 +* `package-lock.json` (use

321 + [`npm-shrinkwrap.json`](/cli/v8/configuring-npm/npm-shrinkwrap-json) if you wish

322 + it to be published)

323 +

324 +### main

325 +

326 +The main field is a module ID that is the primary entry point to your

327 +program. That is, if your package is named `foo`, and a user installs it,

328 +and then does `require("foo")`, then your main module's exports object will

329 +be returned.

330 +

331 +This should be a module relative to the root of your package folder.

332 +

333 +For most modules, it makes the most sense to have a main script and often

334 +not much else.

335 +

336 +If `main` is not set it defaults to `index.js` in the packages root folder.

337 +

338 +### browser

339 +

340 +If your module is meant to be used client-side the browser field should be

341 +used instead of the main field. This is helpful to hint users that it might

342 +rely on primitives that aren't available in Node.js modules. (e.g.

343 +`window`)

344 +

345 +### bin

346 +

347 +A lot of packages have one or more executable files that they'd like to

348 +install into the PATH. npm makes this pretty easy (in fact, it uses this

349 +feature to install the "npm" executable.)

350 +

351 +To use this, supply a `bin` field in your package.json which is a map of

352 +command name to local file name. When this package is installed

353 +globally, that file will be linked where global bins go so it is

354 +available to run by name. When this package is installed as a

355 +dependency in another package, the file will be linked where it will be

356 +available to that package either directly by `npm exec` or by name in other

357 +scripts when invoking them via `npm run-script`.

358 +

359 +

360 +For example, myapp could have this:

361 +

362 +```json

363 +{

364 + "bin": {

365 + "myapp": "./cli.js"

366 + }

367 +}

368 +```

369 +

370 +So, when you install myapp, it'll create a symlink from the `cli.js` script

371 +to `/usr/local/bin/myapp`.

372 +

373 +If you have a single executable, and its name should be the name of the

374 +package, then you can just supply it as a string. For example:

375 +

376 +```json

377 +{

378 + "name": "my-program",

379 + "version": "1.2.5",

380 + "bin": "./path/to/program"

381 +}

382 +```

383 +

384 +would be the same as this:

385 +

386 +```json

387 +{

388 + "name": "my-program",

389 + "version": "1.2.5",

390 + "bin": {

391 + "my-program": "./path/to/program"

392 + }

393 +}

394 +```

395 +

396 +Please make sure that your file(s) referenced in `bin` starts with

397 +`#!/usr/bin/env node`, otherwise the scripts are started without the node

398 +executable!

399 +

400 +Note that you can also set the executable files using [directories.bin](#directoriesbin).

401 +

402 +See [folders](/cli/v8/configuring-npm/folders#executables) for more info on

403 +executables.

404 +

405 +### man

406 +

407 +Specify either a single file or an array of filenames to put in place for

408 +the `man` program to find.

409 +

410 +If only a single file is provided, then it's installed such that it is the

411 +result from `man <pkgname>`, regardless of its actual filename. For

412 +example:

413 +

414 +```json

415 +{

416 + "name": "foo",

417 + "version": "1.2.3",

418 + "description": "A packaged foo fooer for fooing foos",

419 + "main": "foo.js",

420 + "man": "./man/doc.1"

421 +}

422 +```

423 +

424 +would link the `./man/doc.1` file in such that it is the target for `man

425 +foo`

426 +

427 +If the filename doesn't start with the package name, then it's prefixed.

428 +So, this:

429 +

430 +```json

431 +{

432 + "name": "foo",

433 + "version": "1.2.3",

434 + "description": "A packaged foo fooer for fooing foos",

435 + "main": "foo.js",

436 + "man": [

437 + "./man/foo.1",

438 + "./man/bar.1"

439 + ]

440 +}

441 +```

442 +

443 +will create files to do `man foo` and `man foo-bar`.

444 +

445 +Man files must end with a number, and optionally a `.gz` suffix if they are

446 +compressed. The number dictates which man section the file is installed

447 +into.

448 +

449 +```json

450 +{

451 + "name": "foo",

452 + "version": "1.2.3",

453 + "description": "A packaged foo fooer for fooing foos",

454 + "main": "foo.js",

455 + "man": [

456 + "./man/foo.1",

457 + "./man/foo.2"

458 + ]

459 +}

460 +```

461 +

462 +will create entries for `man foo` and `man 2 foo`

463 +

464 +### directories

465 +

466 +The CommonJS [Packages](http://wiki.commonjs.org/wiki/Packages/1.0) spec

467 +details a few ways that you can indicate the structure of your package

468 +using a `directories` object. If you look at [npm's

469 +package.json](https://registry.npmjs.org/npm/latest), you'll see that it

470 +has directories for doc, lib, and man.

471 +

472 +In the future, this information may be used in other creative ways.

473 +

474 +#### directories.bin

475 +

476 +If you specify a `bin` directory in `directories.bin`, all the files in

477 +that folder will be added.

478 +

479 +Because of the way the `bin` directive works, specifying both a `bin` path

480 +and setting `directories.bin` is an error. If you want to specify

481 +individual files, use `bin`, and for all the files in an existing `bin`

482 +directory, use `directories.bin`.

483 +

484 +#### directories.man

485 +

486 +A folder that is full of man pages. Sugar to generate a "man" array by

487 +walking the folder.

488 +

489 +### repository

490 +

491 +Specify the place where your code lives. This is helpful for people who

492 +want to contribute. If the git repo is on GitHub, then the `npm docs`

493 +command will be able to find you.

494 +

495 +Do it like this:

496 +

497 +```json

498 +{

499 + "repository": {

500 + "type": "git",

501 + "url": "https://github.com/npm/cli.git"

502 + }

503 +}

504 +```

505 +

506 +The URL should be a publicly available (perhaps read-only) url that can be

507 +handed directly to a VCS program without any modification. It should not

508 +be a url to an html project page that you put in your browser. It's for

509 +computers.

510 +

511 +For GitHub, GitHub gist, Bitbucket, or GitLab repositories you can use the

512 +same shortcut syntax you use for `npm install`:

513 +

514 +```json

515 +{

516 + "repository": "npm/npm",

517 +

518 + "repository": "github:user/repo",

519 +

520 + "repository": "gist:11081aaa281",

521 +

522 + "repository": "bitbucket:user/repo",

523 +

524 + "repository": "gitlab:user/repo"

525 +}

526 +```

527 +

528 +If the `package.json` for your package is not in the root directory (for

529 +example if it is part of a monorepo), you can specify the directory in

530 +which it lives:

531 +

532 +```json

533 +{

534 + "repository": {

535 + "type": "git",

536 + "url": "https://github.com/facebook/react.git",

537 + "directory": "packages/react-dom"

538 + }

539 +}

540 +```

541 +

542 +### scripts

543 +

544 +The "scripts" property is a dictionary containing script commands that are

545 +run at various times in the lifecycle of your package. The key is the

546 +lifecycle event, and the value is the command to run at that point.

547 +

548 +See [`scripts`](/cli/v8/using-npm/scripts) to find out more about writing package

549 +scripts.

550 +

551 +### config

552 +

553 +A "config" object can be used to set configuration parameters used in

554 +package scripts that persist across upgrades. For instance, if a package

555 +had the following:

556 +

557 +```json

558 +{

559 + "name": "foo",

560 + "config": {

561 + "port": "8080"

562 + }

563 +}

564 +```

565 +

566 +It could also have a "start" command that referenced the

567 +`npm_package_config_port` environment variable.

568 +

569 +### dependencies

570 +

571 +Dependencies are specified in a simple object that maps a package name to a

572 +version range. The version range is a string which has one or more

573 +space-separated descriptors. Dependencies can also be identified with a

574 +tarball or git URL.

575 +

576 +**Please do not put test harnesses or transpilers or other "development"

577 +time tools in your `dependencies` object.** See `devDependencies`, below.

578 +

579 +See [semver](https://github.com/npm/node-semver#versions) for more details about specifying version ranges.

580 +

581 +* `version` Must match `version` exactly

582 +* `>version` Must be greater than `version`

583 +* `>=version` etc

584 +* `<version`

585 +* `<=version`

586 +* `~version` "Approximately equivalent to version" See

587 + [semver](https://github.com/npm/node-semver#versions)

588 +* `^version` "Compatible with version" See [semver](https://github.com/npm/node-semver#versions)

589 +* `1.2.x` 1.2.0, 1.2.1, etc., but not 1.3.0

590 +* `http://...` See 'URLs as Dependencies' below

591 +* `*` Matches any version

592 +* `""` (just an empty string) Same as `*`

593 +* `version1 - version2` Same as `>=version1 <=version2`.

594 +* `range1 || range2` Passes if either range1 or range2 are satisfied.

595 +* `git...` See 'Git URLs as Dependencies' below

596 +* `user/repo` See 'GitHub URLs' below

597 +* `tag` A specific version tagged and published as `tag` See [`npm

598 + dist-tag`](/cli/v8/commands/npm-dist-tag)

599 +* `path/path/path` See [Local Paths](#local-paths) below

600 +

601 +For example, these are all valid:

602 +

603 +```json

604 +{

605 + "dependencies": {

606 + "foo": "1.0.0 - 2.9999.9999",

607 + "bar": ">=1.0.2 <2.1.2",

608 + "baz": ">1.0.2 <=2.3.4",

609 + "boo": "2.0.1",

610 + "qux": "<1.0.0 || >=2.3.1 <2.4.5 || >=2.5.2 <3.0.0",

611 + "asd": "http://asdf.com/asdf.tar.gz",

612 + "til": "~1.2",

613 + "elf": "~1.2.3",

614 + "two": "2.x",

615 + "thr": "3.3.x",

616 + "lat": "latest",

617 + "dyl": "file:../dyl"

618 + }

619 +}

620 +```

621 +

622 +#### URLs as Dependencies

623 +

624 +You may specify a tarball URL in place of a version range.

625 +

626 +This tarball will be downloaded and installed locally to your package at

627 +install time.

628 +

629 +#### Git URLs as Dependencies

630 +

631 +Git urls are of the form:

632 +

633 +```bash

634 +<protocol>://[<user>[:<password>]@]<hostname>[:<port>][:][/]<path>[#<commit-ish> | #semver:<semver>]

635 +```

636 +

637 +`<protocol>` is one of `git`, `git+ssh`, `git+http`, `git+https`, or

638 +`git+file`.

639 +

640 +If `#<commit-ish>` is provided, it will be used to clone exactly that

641 +commit. If the commit-ish has the format `#semver:<semver>`, `<semver>` can

642 +be any valid semver range or exact version, and npm will look for any tags

643 +or refs matching that range in the remote repository, much as it would for

644 +a registry dependency. If neither `#<commit-ish>` or `#semver:<semver>` is

645 +specified, then `master` is used.

646 +

647 +Examples:

648 +

649 +```bash

650 +git+ssh://git@github.com:npm/cli.git#v1.0.27

651 +git+ssh://git@github.com:npm/cli#semver:^5.0

652 +git+https://isaacs@github.com/npm/cli.git

653 +git://github.com/npm/cli.git#v1.0.27

654 +```

655 +

656 +#### GitHub URLs

657 +

658 +As of version 1.1.65, you can refer to GitHub urls as just "foo":

659 +"user/foo-project". Just as with git URLs, a `commit-ish` suffix can be

660 +included. For example:

661 +

662 +```json

663 +{

664 + "name": "foo",

665 + "version": "0.0.0",

666 + "dependencies": {

667 + "express": "expressjs/express",

668 + "mocha": "mochajs/mocha#4727d357ea",

669 + "module": "user/repo#feature\/branch"

670 + }

671 +}

672 +```

673 +

674 +#### Local Paths

675 +

676 +As of version 2.0.0 you can provide a path to a local directory that

677 +contains a package. Local paths can be saved using `npm install -S` or `npm

678 +install --save`, using any of these forms:

679 +

680 +```bash

681 +../foo/bar

682 +~/foo/bar

683 +./foo/bar

684 +/foo/bar

685 +```

686 +

687 +in which case they will be normalized to a relative path and added to your

688 +`package.json`. For example:

689 +

690 +```json

691 +{

692 + "name": "baz",

693 + "dependencies": {

694 + "bar": "file:../foo/bar"

695 + }

696 +}

697 +```

698 +

699 +This feature is helpful for local offline development and creating tests

700 +that require npm installing where you don't want to hit an external server,

701 +but should not be used when publishing packages to the public registry.

702 +

703 +### devDependencies

704 +

705 +If someone is planning on downloading and using your module in their

706 +program, then they probably don't want or need to download and build the

707 +external test or documentation framework that you use.

708 +

709 +In this case, it's best to map these additional items in a

710 +`devDependencies` object.

711 +

712 +These things will be installed when doing `npm link` or `npm install` from

713 +the root of a package, and can be managed like any other npm configuration

714 +param. See [`config`](/cli/v8/using-npm/config) for more on the topic.

715 +

716 +For build steps that are not platform-specific, such as compiling

717 +CoffeeScript or other languages to JavaScript, use the `prepare` script to

718 +do this, and make the required package a devDependency.

719 +

720 +For example:

721 +

722 +```json

723 +{

724 + "name": "ethopia-waza",

725 + "description": "a delightfully fruity coffee varietal",

726 + "version": "1.2.3",

727 + "devDependencies": {

728 + "coffee-script": "~1.6.3"

729 + },

730 + "scripts": {

731 + "prepare": "coffee -o lib/ -c src/waza.coffee"

732 + },

733 + "main": "lib/waza.js"

734 +}

735 +```

736 +

737 +The `prepare` script will be run before publishing, so that users can

738 +consume the functionality without requiring them to compile it themselves.

739 +In dev mode (ie, locally running `npm install`), it'll run this script as

740 +well, so that you can test it easily.

741 +

742 +### peerDependencies

743 +

744 +In some cases, you want to express the compatibility of your package with a

745 +host tool or library, while not necessarily doing a `require` of this host.

746 +This is usually referred to as a *plugin*. Notably, your module may be

747 +exposing a specific interface, expected and specified by the host

748 +documentation.

749 +

750 +For example:

751 +

752 +```json

753 +{

754 + "name": "tea-latte",

755 + "version": "1.3.5",

756 + "peerDependencies": {

757 + "tea": "2.x"

758 + }

759 +}

760 +```

761 +

762 +This ensures your package `tea-latte` can be installed *along* with the

763 +second major version of the host package `tea` only. `npm install

764 +tea-latte` could possibly yield the following dependency graph:

765 +

766 +```bash

767 +├── tea-latte@1.3.5

768 +└── tea@2.2.0

769 +```

770 +

771 +In npm versions 3 through 6, `peerDependencies` were not automatically

772 +installed, and would raise a warning if an invalid version of the peer

773 +dependency was found in the tree. As of npm v7, peerDependencies _are_

774 +installed by default.

775 +

776 +Trying to install another plugin with a conflicting requirement may cause

777 +an error if the tree cannot be resolved correctly. For this reason, make

778 +sure your plugin requirement is as broad as possible, and not to lock it

779 +down to specific patch versions.

780 +

781 +Assuming the host complies with [semver](https://semver.org/), only changes

782 +in the host package's major version will break your plugin. Thus, if you've

783 +worked with every 1.x version of the host package, use `"^1.0"` or `"1.x"`

784 +to express this. If you depend on features introduced in 1.5.2, use

785 +`"^1.5.2"`.

786 +

787 +### peerDependenciesMeta

788 +

789 +When a user installs your package, npm will emit warnings if packages

790 +specified in `peerDependencies` are not already installed. The

791 +`peerDependenciesMeta` field serves to provide npm more information on how

792 +your peer dependencies are to be used. Specifically, it allows peer

793 +dependencies to be marked as optional.

794 +

795 +For example:

796 +

797 +```json

798 +{

799 + "name": "tea-latte",

800 + "version": "1.3.5",

801 + "peerDependencies": {

802 + "tea": "2.x",

803 + "soy-milk": "1.2"

804 + },

805 + "peerDependenciesMeta": {

806 + "soy-milk": {

807 + "optional": true

808 + }

809 + }

810 +}

811 +```

812 +

813 +Marking a peer dependency as optional ensures npm will not emit a warning

814 +if the `soy-milk` package is not installed on the host. This allows you to

815 +integrate and interact with a variety of host packages without requiring

816 +all of them to be installed.

817 +

818 +### bundledDependencies

819 +

820 +This defines an array of package names that will be bundled when publishing

821 +the package.

822 +

823 +In cases where you need to preserve npm packages locally or have them

824 +available through a single file download, you can bundle the packages in a

825 +tarball file by specifying the package names in the `bundledDependencies`

826 +array and executing `npm pack`.

827 +

828 +For example:

829 +

830 +If we define a package.json like this:

831 +

832 +```json

833 +{

834 + "name": "awesome-web-framework",

835 + "version": "1.0.0",

836 + "bundledDependencies": [

837 + "renderized",

838 + "super-streams"

839 + ]

840 +}

841 +```

842 +

843 +we can obtain `awesome-web-framework-1.0.0.tgz` file by running `npm pack`.

844 +This file contains the dependencies `renderized` and `super-streams` which

845 +can be installed in a new project by executing `npm install

846 +awesome-web-framework-1.0.0.tgz`. Note that the package names do not

847 +include any versions, as that information is specified in `dependencies`.

848 +

849 +If this is spelled `"bundleDependencies"`, then that is also honored.

850 +

851 +### optionalDependencies

852 +

853 +If a dependency can be used, but you would like npm to proceed if it cannot

854 +be found or fails to install, then you may put it in the

855 +`optionalDependencies` object. This is a map of package name to version or

856 +url, just like the `dependencies` object. The difference is that build

857 +failures do not cause installation to fail. Running `npm install

858 +--no-optional` will prevent these dependencies from being installed.

859 +

860 +It is still your program's responsibility to handle the lack of the

861 +dependency. For example, something like this:

862 +

863 +```js

864 +try {

865 + var foo = require('foo')

866 + var fooVersion = require('foo/package.json').version

867 +} catch (er) {

868 + foo = null

869 +}

870 +if ( notGoodFooVersion(fooVersion) ) {

871 + foo = null

872 +}

873 +

874 +// .. then later in your program ..

875 +

876 +if (foo) {

877 + foo.doFooThings()

878 +}

879 +```

880 +

881 +Entries in `optionalDependencies` will override entries of the same name in

882 +`dependencies`, so it's usually best to only put in one place.

883 +

884 +### engines

885 +

886 +You can specify the version of node that your stuff works on:

887 +

888 +```json

889 +{

890 + "engines": {

891 + "node": ">=0.10.3 <15"

892 + }

893 +}

894 +```

895 +

896 +And, like with dependencies, if you don't specify the version (or if you

897 +specify "\*" as the version), then any version of node will do.

898 +

899 +You can also use the "engines" field to specify which versions of npm are

900 +capable of properly installing your program. For example:

901 +

902 +```json

903 +{

904 + "engines": {

905 + "npm": "~1.0.20"

906 + }

907 +}

908 +```

909 +

910 +Unless the user has set the `engine-strict` config flag, this field is

911 +advisory only and will only produce warnings when your package is installed

912 +as a dependency.

913 +

914 +### os

915 +

916 +You can specify which operating systems your

917 +module will run on:

918 +

919 +```json

920 +{

921 + "os": [

922 + "darwin",

923 + "linux"

924 + ]

925 +}

926 +```

927 +

928 +You can also block instead of allowing operating systems, just prepend the

929 +blocked os with a '!':

930 +

931 +```json

932 +{

933 + "os": [

934 + "!win32"

935 + ]

936 +}

937 +```

938 +

939 +The host operating system is determined by `process.platform`

940 +

941 +It is allowed to both block and allow an item, although there isn't any

942 +good reason to do this.

943 +

944 +### cpu

945 +

946 +If your code only runs on certain cpu architectures,

947 +you can specify which ones.

948 +

949 +```json

950 +{

951 + "cpu": [

952 + "x64",

953 + "ia32"

954 + ]

955 +}

956 +```

957 +

958 +Like the `os` option, you can also block architectures:

959 +

960 +```json

961 +{

962 + "cpu": [

963 + "!arm",

964 + "!mips"

965 + ]

966 +}

967 +```

968 +

969 +The host architecture is determined by `process.arch`

970 +

971 +### private

972 +

973 +If you set `"private": true` in your package.json, then npm will refuse to

974 +publish it.

975 +

976 +This is a way to prevent accidental publication of private repositories.

977 +If you would like to ensure that a given package is only ever published to

978 +a specific registry (for example, an internal registry), then use the

979 +`publishConfig` dictionary described below to override the `registry`

980 +config param at publish-time.

981 +

982 +### publishConfig

983 +

984 +This is a set of config values that will be used at publish-time. It's

985 +especially handy if you want to set the tag, registry or access, so that

986 +you can ensure that a given package is not tagged with "latest", published

987 +to the global public registry or that a scoped module is private by

988 +default.

989 +

990 +See [`config`](/cli/v8/using-npm/config) to see the list of config options that

991 +can be overridden.

992 +

993 +### workspaces

994 +

995 +The optional `workspaces` field is an array of file patterns that describes

996 +locations within the local file system that the install client should look

997 +up to find each [workspace](/cli/v8/using-npm/workspaces) that needs to be

998 +symlinked to the top level `node_modules` folder.

999 +

1000 +It can describe either the direct paths of the folders to be used as

1001 +workspaces or it can define globs that will resolve to these same folders.

1002 +

1003 +In the following example, all folders located inside the folder

1004 +`./packages` will be treated as workspaces as long as they have valid

1005 +`package.json` files inside them:

1006 +

1007 +```json

1008 +{

1009 + "name": "workspace-example",

1010 + "workspaces": [

1011 + "./packages/*"

1012 + ]

1013 +}

1014 +```

1015 +

1016 +See [`workspaces`](/cli/v8/using-npm/workspaces) for more examples.

1017 +

1018 +### DEFAULT VALUES

1019 +

1020 +npm will default some values based on package contents.

1021 +

1022 +* `"scripts": {"start": "node server.js"}`

1023 +

1024 + If there is a `server.js` file in the root of your package, then npm will

1025 + default the `start` command to `node server.js`.

1026 +

1027 +* `"scripts":{"install": "node-gyp rebuild"}`

1028 +

1029 + If there is a `binding.gyp` file in the root of your package and you have

1030 + not defined an `install` or `preinstall` script, npm will default the

1031 + `install` command to compile using node-gyp.

1032 +

1033 +* `"contributors": [...]`

1034 +

1035 + If there is an `AUTHORS` file in the root of your package, npm will treat

1036 + each line as a `Name <email> (url)` format, where email and url are

1037 + optional. Lines which start with a `#` or are blank, will be ignored.

1038 +

1039 +### SEE ALSO

1040 +

1041 +* [semver](https://github.com/npm/node-semver#versions)

1042 +* [workspaces](/cli/v8/using-npm/workspaces)

1043 +* [npm init](/cli/v8/commands/npm-init)

1044 +* [npm version](/cli/v8/commands/npm-version)

1045 +* [npm config](/cli/v8/commands/npm-config)

1046 +* [npm help](/cli/v8/commands/npm-help)

1047 +* [npm install](/cli/v8/commands/npm-install)

1048 +* [npm publish](/cli/v8/commands/npm-publish)

1049 +* [npm uninstall](/cli/v8/commands/npm-uninstall)

content/cli/v8/configuring-npm/package-lock-json.md new

+246

@@ -0,0 +1,246 @@

1 +---

2 +title: package-lock.json

3 +section: 5

4 +description: A manifestation of the manifest

5 +redirect_from:

6 + - /configuring-npm/package-lock-json

7 + - /configuring-npm/package-lock-json.html

8 + - /files/package-lock.json

9 + - /files/package-lock.json.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/configuring-npm/package-lock-json.md

13 +---

14 +

15 +### Description

16 +

17 +`package-lock.json` is automatically generated for any operations where npm

18 +modifies either the `node_modules` tree, or `package.json`. It describes the

19 +exact tree that was generated, such that subsequent installs are able to

20 +generate identical trees, regardless of intermediate dependency updates.

21 +

22 +This file is intended to be committed into source repositories, and serves

23 +various purposes:

24 +

25 +* Describe a single representation of a dependency tree such that

26 + teammates, deployments, and continuous integration are guaranteed to

27 + install exactly the same dependencies.

28 +

29 +* Provide a facility for users to "time-travel" to previous states of

30 + `node_modules` without having to commit the directory itself.

31 +

32 +* Facilitate greater visibility of tree changes through readable source

33 + control diffs.

34 +

35 +* Optimize the installation process by allowing npm to skip repeated

36 + metadata resolutions for previously-installed packages.

37 +

38 +* As of npm v7, lockfiles include enough information to gain a complete

39 + picture of the package tree, reducing the need to read `package.json`

40 + files, and allowing for significant performance improvements.

41 +

42 +### `package-lock.json` vs `npm-shrinkwrap.json`

43 +

44 +Both of these files have the same format, and perform similar functions in

45 +the root of a project.

46 +

47 +The difference is that `package-lock.json` cannot be published, and it will

48 +be ignored if found in any place other than the root project.

49 +

50 +In contrast, [npm-shrinkwrap.json](/cli/v8/configuring-npm/npm-shrinkwrap-json) allows

51 +publication, and defines the dependency tree from the point encountered.

52 +This is not recommended unless deploying a CLI tool or otherwise using the

53 +publication process for producing production packages.

54 +

55 +If both `package-lock.json` and `npm-shrinkwrap.json` are present in the

56 +root of a project, `npm-shrinkwrap.json` will take precedence and

57 +`package-lock.json` will be ignored.

58 +

59 +### Hidden Lockfiles

60 +

61 +In order to avoid processing the `node_modules` folder repeatedly, npm as

62 +of v7 uses a "hidden" lockfile present in

63 +`node_modules/.package-lock.json`. This contains information about the

64 +tree, and is used in lieu of reading the entire `node_modules` hierarchy

65 +provided that the following conditions are met:

66 +

67 +- All package folders it references exist in the `node_modules` hierarchy.

68 +- No package folders exist in the `node_modules` hierarchy that are not

69 + listed in the lockfile.

70 +- The modified time of the file is at least as recent as all of the package

71 + folders it references.

72 +

73 +That is, the hidden lockfile will only be relevant if it was created as

74 +part of the most recent update to the package tree. If another CLI mutates

75 +the tree in any way, this will be detected, and the hidden lockfile will be

76 +ignored.

77 +

78 +Note that it _is_ possible to manually change the _contents_ of a package

79 +in such a way that the modified time of the package folder is unaffected.

80 +For example, if you add a file to `node_modules/foo/lib/bar.js`, then the

81 +modified time on `node_modules/foo` will not reflect this change. If you

82 +are manually editing files in `node_modules`, it is generally best to

83 +delete the file at `node_modules/.package-lock.json`.

84 +

85 +As the hidden lockfile is ignored by older npm versions, it does not

86 +contain the backwards compatibility affordances present in "normal"

87 +lockfiles. That is, it is `lockfileVersion: 3`, rather than

88 +`lockfileVersion: 2`.

89 +

90 +### Handling Old Lockfiles

91 +

92 +When npm detects a lockfile from npm v6 or before during the package

93 +installation process, it is automatically updated to fetch missing

94 +information from either the `node_modules` tree or (in the case of empty

95 +`node_modules` trees or very old lockfile formats) the npm registry.

96 +

97 +### File Format

98 +

99 +#### `name`

100 +

101 +The name of the package this is a package-lock for. This will match what's

102 +in `package.json`.

103 +

104 +#### `version`

105 +

106 +The version of the package this is a package-lock for. This will match

107 +what's in `package.json`.

108 +

109 +#### `lockfileVersion`

110 +

111 +An integer version, starting at `1` with the version number of this

112 +document whose semantics were used when generating this

113 +`package-lock.json`.

114 +

115 +Note that the file format changed significantly in npm v7 to track

116 +information that would have otherwise required looking in `node_modules` or

117 +the npm registry. Lockfiles generated by npm v7 will contain

118 +`lockfileVersion: 2`.

119 +

120 +* No version provided: an "ancient" shrinkwrap file from a version of npm

121 + prior to npm v5.

122 +* `1`: The lockfile version used by npm v5 and v6.

123 +* `2`: The lockfile version used by npm v7, which is backwards compatible

124 + to v1 lockfiles.

125 +* `3`: The lockfile version used by npm v7, _without_ backwards

126 + compatibility affordances. This is used for the hidden lockfile at

127 + `node_modules/.package-lock.json`, and will likely be used in a future

128 + version of npm, once support for npm v6 is no longer relevant.

129 +

130 +npm will always attempt to get whatever data it can out of a lockfile, even

131 +if it is not a version that it was designed to support.

132 +

133 +#### `packages`

134 +

135 +This is an object that maps package locations to an object containing the

136 +information about that package.

137 +

138 +The root project is typically listed with a key of `""`, and all other

139 +packages are listed with their relative paths from the root project folder.

140 +

141 +Package descriptors have the following fields:

142 +

143 +* version: The version found in `package.json`

144 +

145 +* resolved: The place where the package was actually resolved from. In

146 + the case of packages fetched from the registry, this will be a url to a

147 + tarball. In the case of git dependencies, this will be the full git url

148 + with commit sha. In the case of link dependencies, this will be the

149 + location of the link target. `registry.npmjs.org` is a magic value meaning

150 + "the currently configured registry".

151 +

152 +* integrity: A `sha512` or `sha1` [Standard Subresource

153 + Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)

154 + string for the artifact that was unpacked in this location.

155 +

156 +* link: A flag to indicate that this is a symbolic link. If this is

157 + present, no other fields are specified, since the link target will also

158 + be included in the lockfile.

159 +

160 +* dev, optional, devOptional: If the package is strictly part of the

161 + `devDependencies` tree, then `dev` will be true. If it is strictly part

162 + of the `optionalDependencies` tree, then `optional` will be set. If it

163 + is both a `dev` dependency _and_ an `optional` dependency of a non-dev

164 + dependency, then `devOptional` will be set. (An `optional` dependency of

165 + a `dev` dependency will have both `dev` and `optional` set.)

166 +

167 +* inBundle: A flag to indicate that the package is a bundled dependency.

168 +

169 +* hasInstallScript: A flag to indicate that the package has a `preinstall`,

170 + `install`, or `postinstall` script.

171 +

172 +* hasShrinkwrap: A flag to indicate that the package has an

173 + `npm-shrinkwrap.json` file.

174 +

175 +* bin, license, engines, dependencies, optionalDependencies: fields from

176 + `package.json`

177 +

178 +#### dependencies

179 +

180 +Legacy data for supporting versions of npm that use `lockfileVersion: 1`.

181 +This is a mapping of package names to dependency objects. Because the

182 +object structure is strictly hierarchical, symbolic link dependencies are

183 +somewhat challenging to represent in some cases.

184 +

185 +npm v7 ignores this section entirely if a `packages` section is present,

186 +but does keep it up to date in order to support switching between npm v6

187 +and npm v7.

188 +

189 +Dependency objects have the following fields:

190 +

191 +* version: a specifier that varies depending on the nature of the package,

192 + and is usable in fetching a new copy of it.

193 +

194 + * bundled dependencies: Regardless of source, this is a version number

195 + that is purely for informational purposes.

196 + * registry sources: This is a version number. (eg, `1.2.3`)

197 + * git sources: This is a git specifier with resolved committish. (eg,

198 + `git+https://example.com/foo/bar#115311855adb0789a0466714ed48a1499ffea97e`)

199 + * http tarball sources: This is the URL of the tarball. (eg,

200 + `https://example.com/example-1.3.0.tgz`)

201 + * local tarball sources: This is the file URL of the tarball. (eg

202 + `file:///opt/storage/example-1.3.0.tgz`)

203 + * local link sources: This is the file URL of the link. (eg

204 + `file:libs/our-module`)

205 +

206 +* integrity: A `sha512` or `sha1` [Standard Subresource

207 + Integrity](https://w3c.github.io/webappsec/specs/subresourceintegrity/)

208 + string for the artifact that was unpacked in this location. For git

209 + dependencies, this is the commit sha.

210 +

211 +* resolved: For registry sources this is path of the tarball relative to

212 + the registry URL. If the tarball URL isn't on the same server as the

213 + registry URL then this is a complete URL. `registry.npmjs.org` is a magic

214 + value meaning "the currently configured registry".

215 +

216 +* bundled: If true, this is the bundled dependency and will be installed

217 + by the parent module. When installing, this module will be extracted

218 + from the parent module during the extract phase, not installed as a

219 + separate dependency.

220 +

221 +* dev: If true then this dependency is either a development dependency ONLY

222 + of the top level module or a transitive dependency of one. This is false

223 + for dependencies that are both a development dependency of the top level

224 + and a transitive dependency of a non-development dependency of the top

225 + level.

226 +

227 +* optional: If true then this dependency is either an optional dependency

228 + ONLY of the top level module or a transitive dependency of one. This is

229 + false for dependencies that are both an optional dependency of the top

230 + level and a transitive dependency of a non-optional dependency of the top

231 + level.

232 +

233 +* requires: This is a mapping of module name to version. This is a list of

234 + everything this module requires, regardless of where it will be

235 + installed. The version should match via normal matching rules a

236 + dependency either in our `dependencies` or in a level higher than us.

237 +

238 +* dependencies: The dependencies of this dependency, exactly as at the top

239 + level.

240 +

241 +### See also

242 +

243 +* [npm shrinkwrap](/cli/v8/commands/npm-shrinkwrap)

244 +* [npm-shrinkwrap.json](/cli/v8/configuring-npm/npm-shrinkwrap-json)

245 +* [package.json](/cli/v8/configuring-npm/package-json)

246 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/index.mdx new

+10

@@ -0,0 +1,10 @@

1 +---

2 +redirect_from:

3 + - /cli

4 + - /cli-documentation

5 +github_repo: npm/cli

6 +github_branch: latest

7 +github_path: docs/content/index.mdx

8 +title: CLI documentation

9 +---

10 +<Index depth="1" />

\ No newline at end of file

content/cli/v8/using-npm/config.md new

+2054

@@ -0,0 +1,2054 @@

1 +---

2 +title: config

3 +section: 7

4 +description: More than you probably want to know about npm configuration

5 +redirect_from:

6 + - /using-npm/config

7 + - /using-npm/config.html

8 + - /misc/config

9 + - /misc/config.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/config.md

13 +---

14 +

15 +### Description

16 +

17 +npm gets its configuration values from the following sources, sorted by priority:

18 +

19 +#### Command Line Flags

20 +

21 +Putting `--foo bar` on the command line sets the `foo` configuration

22 +parameter to `"bar"`. A `--` argument tells the cli parser to stop

23 +reading flags. Using `--flag` without specifying any value will set

24 +the value to `true`.

25 +

26 +Example: `--flag1 --flag2` will set both configuration parameters

27 +to `true`, while `--flag1 --flag2 bar` will set `flag1` to `true`,

28 +and `flag2` to `bar`. Finally, `--flag1 --flag2 -- bar` will set

29 +both configuration parameters to `true`, and the `bar` is taken

30 +as a command argument.

31 +

32 +#### Environment Variables

33 +

34 +Any environment variables that start with `npm_config_` will be

35 +interpreted as a configuration parameter. For example, putting

36 +`npm_config_foo=bar` in your environment will set the `foo`

37 +configuration parameter to `bar`. Any environment configurations that

38 +are not given a value will be given the value of `true`. Config

39 +values are case-insensitive, so `NPM_CONFIG_FOO=bar` will work the

40 +same. However, please note that inside [`scripts`](/cli/v8/using-npm/scripts)

41 +npm will set its own environment variables and Node will prefer

42 +those lowercase versions over any uppercase ones that you might set.

43 +For details see [this issue](https://github.com/npm/npm/issues/14528).

44 +

45 +Notice that you need to use underscores instead of dashes, so `--allow-same-version`

46 +would become `npm_config_allow_same_version=true`.

47 +

48 +#### npmrc Files

49 +

50 +The four relevant files are:

51 +

52 +* per-project configuration file (`/path/to/my/project/.npmrc`)

53 +* per-user configuration file (defaults to `$HOME/.npmrc`; configurable via CLI

54 + option `--userconfig` or environment variable `$NPM_CONFIG_USERCONFIG`)

55 +* global configuration file (defaults to `$PREFIX/etc/npmrc`; configurable via

56 + CLI option `--globalconfig` or environment variable `$NPM_CONFIG_GLOBALCONFIG`)

57 +* npm's built-in configuration file (`/path/to/npm/npmrc`)

58 +

59 +See [npmrc](/cli/v8/configuring-npm/npmrc) for more details.

60 +

61 +#### Default Configs

62 +

63 +Run `npm config ls -l` to see a set of configuration parameters that are

64 +internal to npm, and are defaults if nothing else is specified.

65 +

66 +### Shorthands and Other CLI Niceties

67 +

68 +The following shorthands are parsed on the command-line:

69 +

70 +<!-- AUTOGENERATED CONFIG SHORTHANDS START -->

71 +<!-- automatically generated, do not edit manually -->

72 +<!-- see lib/utils/config/definitions.js -->

73 +* `-a`: `--all`

74 +* `--enjoy-by`: `--before`

75 +* `-c`: `--call`

76 +* `--desc`: `--description`

77 +* `-f`: `--force`

78 +* `-g`: `--global`

79 +* `-L`: `--location`

80 +* `-d`: `--loglevel info`

81 +* `-s`: `--loglevel silent`

82 +* `--silent`: `--loglevel silent`

83 +* `--ddd`: `--loglevel silly`

84 +* `--dd`: `--loglevel verbose`

85 +* `--verbose`: `--loglevel verbose`

86 +* `-q`: `--loglevel warn`

87 +* `--quiet`: `--loglevel warn`

88 +* `-l`: `--long`

89 +* `-m`: `--message`

90 +* `--local`: `--no-global`

91 +* `-n`: `--no-yes`

92 +* `--no`: `--no-yes`

93 +* `-p`: `--parseable`

94 +* `--porcelain`: `--parseable`

95 +* `-C`: `--prefix`

96 +* `--readonly`: `--read-only`

97 +* `--reg`: `--registry`

98 +* `-S`: `--save`

99 +* `-B`: `--save-bundle`

100 +* `-D`: `--save-dev`

101 +* `-E`: `--save-exact`

102 +* `-O`: `--save-optional`

103 +* `-P`: `--save-prod`

104 +* `-?`: `--usage`

105 +* `-h`: `--usage`

106 +* `-H`: `--usage`

107 +* `--help`: `--usage`

108 +* `-v`: `--version`

109 +* `-w`: `--workspace`

110 +* `--ws`: `--workspaces`

111 +* `-y`: `--yes`

112 +

113 +<!-- automatically generated, do not edit manually -->

114 +<!-- see lib/utils/config/definitions.js -->

115 +<!-- AUTOGENERATED CONFIG SHORTHANDS END -->

116 +

117 +If the specified configuration param resolves unambiguously to a known

118 +configuration parameter, then it is expanded to that configuration

119 +parameter. For example:

120 +

121 +```bash

122 +npm ls --par

123 +# same as:

124 +npm ls --parseable

125 +```

126 +

127 +If multiple single-character shorthands are strung together, and the

128 +resulting combination is unambiguously not some other configuration

129 +param, then it is expanded to its various component pieces. For

130 +example:

131 +

132 +```bash

133 +npm ls -gpld

134 +# same as:

135 +npm ls --global --parseable --long --loglevel info

136 +```

137 +

138 +### Config Settings

139 +

140 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS START -->

141 +<!-- automatically generated, do not edit manually -->

142 +<!-- see lib/utils/config/definitions.js -->

143 +#### `_auth`

144 +

145 +* Default: null

146 +* Type: null or String

147 +

148 +A basic-auth string to use when authenticating against the npm registry.

149 +

150 +Warning: This should generally not be set via a command-line option. It is

151 +safer to use a registry-provided authentication bearer token stored in the

152 +~/.npmrc file by running `npm login`.

153 +

154 +<!-- automatically generated, do not edit manually -->

155 +<!-- see lib/utils/config/definitions.js -->

156 +

157 +#### `access`

158 +

159 +* Default: 'restricted' for scoped packages, 'public' for unscoped packages

160 +* Type: null, "restricted", or "public"

161 +

162 +When publishing scoped packages, the access level defaults to `restricted`.

163 +If you want your scoped package to be publicly viewable (and installable)

164 +set `--access=public`. The only valid values for `access` are `public` and

165 +`restricted`. Unscoped packages _always_ have an access level of `public`.

166 +

167 +Note: Using the `--access` flag on the `npm publish` command will only set

168 +the package access level on the initial publish of the package. Any

169 +subsequent `npm publish` commands using the `--access` flag will not have an

170 +effect to the access level. To make changes to the access level after the

171 +initial publish use `npm access`.

172 +

173 +<!-- automatically generated, do not edit manually -->

174 +<!-- see lib/utils/config/definitions.js -->

175 +

176 +#### `all`

177 +

178 +* Default: false

179 +* Type: Boolean

180 +

181 +When running `npm outdated` and `npm ls`, setting `--all` will show all

182 +outdated or installed packages, rather than only those directly depended

183 +upon by the current project.

184 +

185 +<!-- automatically generated, do not edit manually -->

186 +<!-- see lib/utils/config/definitions.js -->

187 +

188 +#### `allow-same-version`

189 +

190 +* Default: false

191 +* Type: Boolean

192 +

193 +Prevents throwing an error when `npm version` is used to set the new version

194 +to the same value as the current version.

195 +

196 +<!-- automatically generated, do not edit manually -->

197 +<!-- see lib/utils/config/definitions.js -->

198 +

199 +#### `audit`

200 +

201 +* Default: true

202 +* Type: Boolean

203 +

204 +When "true" submit audit reports alongside the current npm command to the

205 +default registry and all registries configured for scopes. See the

206 +documentation for [`npm audit`](/cli/v8/commands/npm-audit) for details on what is

207 +submitted.

208 +

209 +<!-- automatically generated, do not edit manually -->

210 +<!-- see lib/utils/config/definitions.js -->

211 +

212 +#### `audit-level`

213 +

214 +* Default: null

215 +* Type: null, "info", "low", "moderate", "high", "critical", or "none"

216 +

217 +The minimum level of vulnerability for `npm audit` to exit with a non-zero

218 +exit code.

219 +

220 +<!-- automatically generated, do not edit manually -->

221 +<!-- see lib/utils/config/definitions.js -->

222 +

223 +#### `before`

224 +

225 +* Default: null

226 +* Type: null or Date

227 +

228 +If passed to `npm install`, will rebuild the npm tree such that only

229 +versions that were available **on or before** the `--before` time get

230 +installed. If there's no versions available for the current set of direct

231 +dependencies, the command will error.

232 +

233 +If the requested version is a `dist-tag` and the given tag does not pass the

234 +`--before` filter, the most recent version less than or equal to that tag

235 +will be used. For example, `foo@latest` might install `foo@1.2` even though

236 +`latest` is `2.0`.

237 +

238 +<!-- automatically generated, do not edit manually -->

239 +<!-- see lib/utils/config/definitions.js -->

240 +

241 +#### `bin-links`

242 +

243 +* Default: true

244 +* Type: Boolean

245 +

246 +Tells npm to create symlinks (or `.cmd` shims on Windows) for package

247 +executables.

248 +

249 +Set to false to have it not do this. This can be used to work around the

250 +fact that some file systems don't support symlinks, even on ostensibly Unix

251 +systems.

252 +

253 +<!-- automatically generated, do not edit manually -->

254 +<!-- see lib/utils/config/definitions.js -->

255 +

256 +#### `browser`

257 +

258 +* Default: OS X: `"open"`, Windows: `"start"`, Others: `"xdg-open"`

259 +* Type: null, Boolean, or String

260 +

261 +The browser that is called by npm commands to open websites.

262 +

263 +Set to `false` to suppress browser behavior and instead print urls to

264 +terminal.

265 +

266 +Set to `true` to use default system URL opener.

267 +

268 +<!-- automatically generated, do not edit manually -->

269 +<!-- see lib/utils/config/definitions.js -->

270 +

271 +#### `ca`

272 +

273 +* Default: null

274 +* Type: null or String (can be set multiple times)

275 +

276 +The Certificate Authority signing certificate that is trusted for SSL

277 +connections to the registry. Values should be in PEM format (Windows calls

278 +it "Base-64 encoded X.509 (.CER)") with newlines replaced by the string

279 +"\n". For example:

280 +

281 +```ini

282 +ca="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

283 +```

284 +

285 +Set to `null` to only allow "known" registrars, or to a specific CA cert to

286 +trust only that specific signing authority.

287 +

288 +Multiple CAs can be trusted by specifying an array of certificates:

289 +

290 +```ini

291 +ca[]="..."

292 +ca[]="..."

293 +```

294 +

295 +See also the `strict-ssl` config.

296 +

297 +<!-- automatically generated, do not edit manually -->

298 +<!-- see lib/utils/config/definitions.js -->

299 +

300 +#### `cache`

301 +

302 +* Default: Windows: `%LocalAppData%\npm-cache`, Posix: `~/.npm`

303 +* Type: Path

304 +

305 +The location of npm's cache directory. See [`npm

306 +cache`](/cli/v8/commands/npm-cache)

307 +

308 +<!-- automatically generated, do not edit manually -->

309 +<!-- see lib/utils/config/definitions.js -->

310 +

311 +#### `cafile`

312 +

313 +* Default: null

314 +* Type: Path

315 +

316 +A path to a file containing one or multiple Certificate Authority signing

317 +certificates. Similar to the `ca` setting, but allows for multiple CA's, as

318 +well as for the CA information to be stored in a file on disk.

319 +

320 +<!-- automatically generated, do not edit manually -->

321 +<!-- see lib/utils/config/definitions.js -->

322 +

323 +#### `call`

324 +

325 +* Default: ""

326 +* Type: String

327 +

328 +Optional companion option for `npm exec`, `npx` that allows for specifying a

329 +custom command to be run along with the installed packages.

330 +

331 +```bash

332 +npm exec --package yo --package generator-node --call "yo node"

333 +```

334 +

335 +

336 +<!-- automatically generated, do not edit manually -->

337 +<!-- see lib/utils/config/definitions.js -->

338 +

339 +#### `cert`

340 +

341 +* Default: null

342 +* Type: null or String

343 +

344 +A client certificate to pass when accessing the registry. Values should be

345 +in PEM format (Windows calls it "Base-64 encoded X.509 (.CER)") with

346 +newlines replaced by the string "\n". For example:

347 +

348 +```ini

349 +cert="-----BEGIN CERTIFICATE-----\nXXXX\nXXXX\n-----END CERTIFICATE-----"

350 +```

351 +

352 +It is _not_ the path to a certificate file (and there is no "certfile"

353 +option).

354 +

355 +<!-- automatically generated, do not edit manually -->

356 +<!-- see lib/utils/config/definitions.js -->

357 +

358 +#### `ci-name`

359 +

360 +* Default: The name of the current CI system, or `null` when not on a known CI

361 + platform.

362 +* Type: null or String

363 +

364 +The name of a continuous integration system. If not set explicitly, npm will

365 +detect the current CI environment using the

366 +[`@npmcli/ci-detect`](http://npm.im/@npmcli/ci-detect) module.

367 +

368 +<!-- automatically generated, do not edit manually -->

369 +<!-- see lib/utils/config/definitions.js -->

370 +

371 +#### `cidr`

372 +

373 +* Default: null

374 +* Type: null or String (can be set multiple times)

375 +

376 +This is a list of CIDR address to be used when configuring limited access

377 +tokens with the `npm token create` command.

378 +

379 +<!-- automatically generated, do not edit manually -->

380 +<!-- see lib/utils/config/definitions.js -->

381 +

382 +#### `color`

383 +

384 +* Default: true unless the NO_COLOR environ is set to something other than '0'

385 +* Type: "always" or Boolean

386 +

387 +If false, never shows colors. If `"always"` then always shows colors. If

388 +true, then only prints color codes for tty file descriptors.

389 +

390 +<!-- automatically generated, do not edit manually -->

391 +<!-- see lib/utils/config/definitions.js -->

392 +

393 +#### `commit-hooks`

394 +

395 +* Default: true

396 +* Type: Boolean

397 +

398 +Run git commit hooks when using the `npm version` command.

399 +

400 +<!-- automatically generated, do not edit manually -->

401 +<!-- see lib/utils/config/definitions.js -->

402 +

403 +#### `depth`

404 +

405 +* Default: `Infinity` if `--all` is set, otherwise `1`

406 +* Type: null or Number

407 +

408 +The depth to go when recursing packages for `npm ls`.

409 +

410 +If not set, `npm ls` will show only the immediate dependencies of the root

411 +project. If `--all` is set, then npm will show all dependencies by default.

412 +

413 +<!-- automatically generated, do not edit manually -->

414 +<!-- see lib/utils/config/definitions.js -->

415 +

416 +#### `description`

417 +

418 +* Default: true

419 +* Type: Boolean

420 +

421 +Show the description in `npm search`

422 +

423 +<!-- automatically generated, do not edit manually -->

424 +<!-- see lib/utils/config/definitions.js -->

425 +

426 +#### `diff`

427 +

428 +* Default:

429 +* Type: String (can be set multiple times)

430 +

431 +Define arguments to compare in `npm diff`.

432 +

433 +<!-- automatically generated, do not edit manually -->

434 +<!-- see lib/utils/config/definitions.js -->

435 +

436 +#### `diff-dst-prefix`

437 +

438 +* Default: "b/"

439 +* Type: String

440 +

441 +Destination prefix to be used in `npm diff` output.

442 +

443 +<!-- automatically generated, do not edit manually -->

444 +<!-- see lib/utils/config/definitions.js -->

445 +

446 +#### `diff-ignore-all-space`

447 +

448 +* Default: false

449 +* Type: Boolean

450 +

451 +Ignore whitespace when comparing lines in `npm diff`.

452 +

453 +<!-- automatically generated, do not edit manually -->

454 +<!-- see lib/utils/config/definitions.js -->

455 +

456 +#### `diff-name-only`

457 +

458 +* Default: false

459 +* Type: Boolean

460 +

461 +Prints only filenames when using `npm diff`.

462 +

463 +<!-- automatically generated, do not edit manually -->

464 +<!-- see lib/utils/config/definitions.js -->

465 +

466 +#### `diff-no-prefix`

467 +

468 +* Default: false

469 +* Type: Boolean

470 +

471 +Do not show any source or destination prefix in `npm diff` output.

472 +

473 +Note: this causes `npm diff` to ignore the `--diff-src-prefix` and

474 +`--diff-dst-prefix` configs.

475 +

476 +<!-- automatically generated, do not edit manually -->

477 +<!-- see lib/utils/config/definitions.js -->

478 +

479 +#### `diff-src-prefix`

480 +

481 +* Default: "a/"

482 +* Type: String

483 +

484 +Source prefix to be used in `npm diff` output.

485 +

486 +<!-- automatically generated, do not edit manually -->

487 +<!-- see lib/utils/config/definitions.js -->

488 +

489 +#### `diff-text`

490 +

491 +* Default: false

492 +* Type: Boolean

493 +

494 +Treat all files as text in `npm diff`.

495 +

496 +<!-- automatically generated, do not edit manually -->

497 +<!-- see lib/utils/config/definitions.js -->

498 +

499 +#### `diff-unified`

500 +

501 +* Default: 3

502 +* Type: Number

503 +

504 +The number of lines of context to print in `npm diff`.

505 +

506 +<!-- automatically generated, do not edit manually -->

507 +<!-- see lib/utils/config/definitions.js -->

508 +

509 +#### `dry-run`

510 +

511 +* Default: false

512 +* Type: Boolean

513 +

514 +Indicates that you don't want npm to make any changes and that it should

515 +only report what it would have done. This can be passed into any of the

516 +commands that modify your local installation, eg, `install`, `update`,

517 +`dedupe`, `uninstall`, as well as `pack` and `publish`.

518 +

519 +Note: This is NOT honored by other network related commands, eg `dist-tags`,

520 +`owner`, etc.

521 +

522 +<!-- automatically generated, do not edit manually -->

523 +<!-- see lib/utils/config/definitions.js -->

524 +

525 +#### `editor`

526 +

527 +* Default: The EDITOR or VISUAL environment variables, or 'notepad.exe' on

528 + Windows, or 'vim' on Unix systems

529 +* Type: String

530 +

531 +The command to run for `npm edit` and `npm config edit`.

532 +

533 +<!-- automatically generated, do not edit manually -->

534 +<!-- see lib/utils/config/definitions.js -->

535 +

536 +#### `engine-strict`

537 +

538 +* Default: false

539 +* Type: Boolean

540 +

541 +If set to true, then npm will stubbornly refuse to install (or even consider

542 +installing) any package that claims to not be compatible with the current

543 +Node.js version.

544 +

545 +This can be overridden by setting the `--force` flag.

546 +

547 +<!-- automatically generated, do not edit manually -->

548 +<!-- see lib/utils/config/definitions.js -->

549 +

550 +#### `fetch-retries`

551 +

552 +* Default: 2

553 +* Type: Number

554 +

555 +The "retries" config for the `retry` module to use when fetching packages

556 +from the registry.

557 +

558 +npm will retry idempotent read requests to the registry in the case of

559 +network failures or 5xx HTTP errors.

560 +

561 +<!-- automatically generated, do not edit manually -->

562 +<!-- see lib/utils/config/definitions.js -->

563 +

564 +#### `fetch-retry-factor`

565 +

566 +* Default: 10

567 +* Type: Number

568 +

569 +The "factor" config for the `retry` module to use when fetching packages.

570 +

571 +<!-- automatically generated, do not edit manually -->

572 +<!-- see lib/utils/config/definitions.js -->

573 +

574 +#### `fetch-retry-maxtimeout`

575 +

576 +* Default: 60000 (1 minute)

577 +* Type: Number

578 +

579 +The "maxTimeout" config for the `retry` module to use when fetching

580 +packages.

581 +

582 +<!-- automatically generated, do not edit manually -->

583 +<!-- see lib/utils/config/definitions.js -->

584 +

585 +#### `fetch-retry-mintimeout`

586 +

587 +* Default: 10000 (10 seconds)

588 +* Type: Number

589 +

590 +The "minTimeout" config for the `retry` module to use when fetching

591 +packages.

592 +

593 +<!-- automatically generated, do not edit manually -->

594 +<!-- see lib/utils/config/definitions.js -->

595 +

596 +#### `fetch-timeout`

597 +

598 +* Default: 300000 (5 minutes)

599 +* Type: Number

600 +

601 +The maximum amount of time to wait for HTTP requests to complete.

602 +

603 +<!-- automatically generated, do not edit manually -->

604 +<!-- see lib/utils/config/definitions.js -->

605 +

606 +#### `force`

607 +

608 +* Default: false

609 +* Type: Boolean

610 +

611 +Removes various protections against unfortunate side effects, common

612 +mistakes, unnecessary performance degradation, and malicious input.

613 +

614 +* Allow clobbering non-npm files in global installs.

615 +* Allow the `npm version` command to work on an unclean git repository.

616 +* Allow deleting the cache folder with `npm cache clean`.

617 +* Allow installing packages that have an `engines` declaration requiring a

618 + different version of npm.

619 +* Allow installing packages that have an `engines` declaration requiring a

620 + different version of `node`, even if `--engine-strict` is enabled.

621 +* Allow `npm audit fix` to install modules outside your stated dependency

622 + range (including SemVer-major changes).

623 +* Allow unpublishing all versions of a published package.

624 +* Allow conflicting peerDependencies to be installed in the root project.

625 +* Implicitly set `--yes` during `npm init`.

626 +* Allow clobbering existing values in `npm pkg`

627 +

628 +If you don't have a clear idea of what you want to do, it is strongly

629 +recommended that you do not use this option!

630 +

631 +<!-- automatically generated, do not edit manually -->

632 +<!-- see lib/utils/config/definitions.js -->

633 +

634 +#### `foreground-scripts`

635 +

636 +* Default: false

637 +* Type: Boolean

638 +

639 +Run all build scripts (ie, `preinstall`, `install`, and `postinstall`)

640 +scripts for installed packages in the foreground process, sharing standard

641 +input, output, and error with the main npm process.

642 +

643 +Note that this will generally make installs run slower, and be much noisier,

644 +but can be useful for debugging.

645 +

646 +<!-- automatically generated, do not edit manually -->

647 +<!-- see lib/utils/config/definitions.js -->

648 +

649 +#### `format-package-lock`

650 +

651 +* Default: true

652 +* Type: Boolean

653 +

654 +Format `package-lock.json` or `npm-shrinkwrap.json` as a human readable

655 +file.

656 +

657 +<!-- automatically generated, do not edit manually -->

658 +<!-- see lib/utils/config/definitions.js -->

659 +

660 +#### `fund`

661 +

662 +* Default: true

663 +* Type: Boolean

664 +

665 +When "true" displays the message at the end of each `npm install`

666 +acknowledging the number of dependencies looking for funding. See [`npm

667 +fund`](/cli/v8/commands/npm-fund) for details.

668 +

669 +<!-- automatically generated, do not edit manually -->

670 +<!-- see lib/utils/config/definitions.js -->

671 +

672 +#### `git`

673 +

674 +* Default: "git"

675 +* Type: String

676 +

677 +The command to use for git commands. If git is installed on the computer,

678 +but is not in the `PATH`, then set this to the full path to the git binary.

679 +

680 +<!-- automatically generated, do not edit manually -->

681 +<!-- see lib/utils/config/definitions.js -->

682 +

683 +#### `git-tag-version`

684 +

685 +* Default: true

686 +* Type: Boolean

687 +

688 +Tag the commit when using the `npm version` command.

689 +

690 +<!-- automatically generated, do not edit manually -->

691 +<!-- see lib/utils/config/definitions.js -->

692 +

693 +#### `global`

694 +

695 +* Default: false

696 +* Type: Boolean

697 +

698 +Operates in "global" mode, so that packages are installed into the `prefix`

699 +folder instead of the current working directory. See

700 +[folders](/cli/v8/configuring-npm/folders) for more on the differences in behavior.

701 +

702 +* packages are installed into the `{prefix}/lib/node_modules` folder, instead

703 + of the current working directory.

704 +* bin files are linked to `{prefix}/bin`

705 +* man pages are linked to `{prefix}/share/man`

706 +

707 +<!-- automatically generated, do not edit manually -->

708 +<!-- see lib/utils/config/definitions.js -->

709 +

710 +#### `global-style`

711 +

712 +* Default: false

713 +* Type: Boolean

714 +

715 +Causes npm to install the package into your local `node_modules` folder with

716 +the same layout it uses with the global `node_modules` folder. Only your

717 +direct dependencies will show in `node_modules` and everything they depend

718 +on will be flattened in their `node_modules` folders. This obviously will

719 +eliminate some deduping. If used with `legacy-bundling`, `legacy-bundling`

720 +will be preferred.

721 +

722 +<!-- automatically generated, do not edit manually -->

723 +<!-- see lib/utils/config/definitions.js -->

724 +

725 +#### `globalconfig`

726 +

727 +* Default: The global --prefix setting plus 'etc/npmrc'. For example,

728 + '/usr/local/etc/npmrc'

729 +* Type: Path

730 +

731 +The config file to read for global config options.

732 +

733 +<!-- automatically generated, do not edit manually -->

734 +<!-- see lib/utils/config/definitions.js -->

735 +

736 +#### `heading`

737 +

738 +* Default: "npm"

739 +* Type: String

740 +

741 +The string that starts all the debugging log output.

742 +

743 +<!-- automatically generated, do not edit manually -->

744 +<!-- see lib/utils/config/definitions.js -->

745 +

746 +#### `https-proxy`

747 +

748 +* Default: null

749 +* Type: null or URL

750 +

751 +A proxy to use for outgoing https requests. If the `HTTPS_PROXY` or

752 +`https_proxy` or `HTTP_PROXY` or `http_proxy` environment variables are set,

753 +proxy settings will be honored by the underlying `make-fetch-happen`

754 +library.

755 +

756 +<!-- automatically generated, do not edit manually -->

757 +<!-- see lib/utils/config/definitions.js -->

758 +

759 +#### `if-present`

760 +

761 +* Default: false

762 +* Type: Boolean

763 +

764 +If true, npm will not exit with an error code when `run-script` is invoked

765 +for a script that isn't defined in the `scripts` section of `package.json`.

766 +This option can be used when it's desirable to optionally run a script when

767 +it's present and fail if the script fails. This is useful, for example, when

768 +running scripts that may only apply for some builds in an otherwise generic

769 +CI setup.

770 +

771 +<!-- automatically generated, do not edit manually -->

772 +<!-- see lib/utils/config/definitions.js -->

773 +

774 +#### `ignore-scripts`

775 +

776 +* Default: false

777 +* Type: Boolean

778 +

779 +If true, npm does not run scripts specified in package.json files.

780 +

781 +Note that commands explicitly intended to run a particular script, such as

782 +`npm start`, `npm stop`, `npm restart`, `npm test`, and `npm run-script`

783 +will still run their intended script if `ignore-scripts` is set, but they

784 +will *not* run any pre- or post-scripts.

785 +

786 +<!-- automatically generated, do not edit manually -->

787 +<!-- see lib/utils/config/definitions.js -->

788 +

789 +#### `include`

790 +

791 +* Default:

792 +* Type: "prod", "dev", "optional", or "peer" (can be set multiple times)

793 +

794 +Option that allows for defining which types of dependencies to install.

795 +

796 +This is the inverse of `--omit=<type>`.

797 +

798 +Dependency types specified in `--include` will not be omitted, regardless of

799 +the order in which omit/include are specified on the command-line.

800 +

801 +<!-- automatically generated, do not edit manually -->

802 +<!-- see lib/utils/config/definitions.js -->

803 +

804 +#### `include-staged`

805 +

806 +* Default: false

807 +* Type: Boolean

808 +

809 +Allow installing "staged" published packages, as defined by [npm RFC PR

810 +#92](https://github.com/npm/rfcs/pull/92).

811 +

812 +This is experimental, and not implemented by the npm public registry.

813 +

814 +<!-- automatically generated, do not edit manually -->

815 +<!-- see lib/utils/config/definitions.js -->

816 +

817 +#### `include-workspace-root`

818 +

819 +* Default: false

820 +* Type: Boolean

821 +

822 +Include the workspace root when workspaces are enabled for a command.

823 +

824 +When false, specifying individual workspaces via the `workspace` config, or

825 +all workspaces via the `workspaces` flag, will cause npm to operate only on

826 +the specified workspaces, and not on the root project.

827 +

828 +<!-- automatically generated, do not edit manually -->

829 +<!-- see lib/utils/config/definitions.js -->

830 +

831 +#### `init-author-email`

832 +

833 +* Default: ""

834 +* Type: String

835 +

836 +The value `npm init` should use by default for the package author's email.

837 +

838 +<!-- automatically generated, do not edit manually -->

839 +<!-- see lib/utils/config/definitions.js -->

840 +

841 +#### `init-author-name`

842 +

843 +* Default: ""

844 +* Type: String

845 +

846 +The value `npm init` should use by default for the package author's name.

847 +

848 +<!-- automatically generated, do not edit manually -->

849 +<!-- see lib/utils/config/definitions.js -->

850 +

851 +#### `init-author-url`

852 +

853 +* Default: ""

854 +* Type: "" or URL

855 +

856 +The value `npm init` should use by default for the package author's

857 +homepage.

858 +

859 +<!-- automatically generated, do not edit manually -->

860 +<!-- see lib/utils/config/definitions.js -->

861 +

862 +#### `init-license`

863 +

864 +* Default: "ISC"

865 +* Type: String

866 +

867 +The value `npm init` should use by default for the package license.

868 +

869 +<!-- automatically generated, do not edit manually -->

870 +<!-- see lib/utils/config/definitions.js -->

871 +

872 +#### `init-module`

873 +

874 +* Default: "~/.npm-init.js"

875 +* Type: Path

876 +

877 +A module that will be loaded by the `npm init` command. See the

878 +documentation for the

879 +[init-package-json](https://github.com/npm/init-package-json) module for

880 +more information, or [npm init](/cli/v8/commands/npm-init).

881 +

882 +<!-- automatically generated, do not edit manually -->

883 +<!-- see lib/utils/config/definitions.js -->

884 +

885 +#### `init-version`

886 +

887 +* Default: "1.0.0"

888 +* Type: SemVer string

889 +

890 +The value that `npm init` should use by default for the package version

891 +number, if not already set in package.json.

892 +

893 +<!-- automatically generated, do not edit manually -->

894 +<!-- see lib/utils/config/definitions.js -->

895 +

896 +#### `json`

897 +

898 +* Default: false

899 +* Type: Boolean

900 +

901 +Whether or not to output JSON data, rather than the normal output.

902 +

903 +* In `npm pkg set` it enables parsing set values with JSON.parse() before

904 + saving them to your `package.json`.

905 +

906 +Not supported by all npm commands.

907 +

908 +<!-- automatically generated, do not edit manually -->

909 +<!-- see lib/utils/config/definitions.js -->

910 +

911 +#### `key`

912 +

913 +* Default: null

914 +* Type: null or String

915 +

916 +A client key to pass when accessing the registry. Values should be in PEM

917 +format with newlines replaced by the string "\n". For example:

918 +

919 +```ini

920 +key="-----BEGIN PRIVATE KEY-----\nXXXX\nXXXX\n-----END PRIVATE KEY-----"

921 +```

922 +

923 +It is _not_ the path to a key file (and there is no "keyfile" option).

924 +

925 +<!-- automatically generated, do not edit manually -->

926 +<!-- see lib/utils/config/definitions.js -->

927 +

928 +#### `legacy-bundling`

929 +

930 +* Default: false

931 +* Type: Boolean

932 +

933 +Causes npm to install the package such that versions of npm prior to 1.4,

934 +such as the one included with node 0.8, can install the package. This

935 +eliminates all automatic deduping. If used with `global-style` this option

936 +will be preferred.

937 +

938 +<!-- automatically generated, do not edit manually -->

939 +<!-- see lib/utils/config/definitions.js -->

940 +

941 +#### `legacy-peer-deps`

942 +

943 +* Default: false

944 +* Type: Boolean

945 +

946 +Causes npm to completely ignore `peerDependencies` when building a package

947 +tree, as in npm versions 3 through 6.

948 +

949 +If a package cannot be installed because of overly strict `peerDependencies`

950 +that collide, it provides a way to move forward resolving the situation.

951 +

952 +This differs from `--omit=peer`, in that `--omit=peer` will avoid unpacking

953 +`peerDependencies` on disk, but will still design a tree such that

954 +`peerDependencies` _could_ be unpacked in a correct place.

955 +

956 +Use of `legacy-peer-deps` is not recommended, as it will not enforce the

957 +`peerDependencies` contract that meta-dependencies may rely on.

958 +

959 +<!-- automatically generated, do not edit manually -->

960 +<!-- see lib/utils/config/definitions.js -->

961 +

962 +#### `link`

963 +

964 +* Default: false

965 +* Type: Boolean

966 +

967 +Used with `npm ls`, limiting output to only those packages that are linked.

968 +

969 +<!-- automatically generated, do not edit manually -->

970 +<!-- see lib/utils/config/definitions.js -->

971 +

972 +#### `local-address`

973 +

974 +* Default: null

975 +* Type: IP Address

976 +

977 +The IP address of the local interface to use when making connections to the

978 +npm registry. Must be IPv4 in versions of Node prior to 0.12.

979 +

980 +<!-- automatically generated, do not edit manually -->

981 +<!-- see lib/utils/config/definitions.js -->

982 +

983 +#### `location`

984 +

985 +* Default: "user" unless `--global` is passed, which will also set this value

986 + to "global"

987 +* Type: "global", "user", or "project"

988 +

989 +When passed to `npm config` this refers to which config file to use.

990 +

991 +<!-- automatically generated, do not edit manually -->

992 +<!-- see lib/utils/config/definitions.js -->

993 +

994 +#### `lockfile-version`

995 +

996 +* Default: Version 2 if no lockfile or current lockfile version less than or

997 + equal to 2, otherwise maintain current lockfile version

998 +* Type: null, 1, 2, 3, "1", "2", or "3"

999 +

1000 +Set the lockfile format version to be used in package-lock.json and

1001 +npm-shrinkwrap-json files. Possible options are:

1002 +

1003 +1: The lockfile version used by npm versions 5 and 6. Lacks some data that

1004 +is used during the install, resulting in slower and possibly less

1005 +deterministic installs. Prevents lockfile churn when interoperating with

1006 +older npm versions.

1007 +

1008 +2: The default lockfile version used by npm version 7. Includes both the

1009 +version 1 lockfile data and version 3 lockfile data, for maximum determinism

1010 +and interoperability, at the expense of more bytes on disk.

1011 +

1012 +3: Only the new lockfile information introduced in npm version 7. Smaller on

1013 +disk than lockfile version 2, but not interoperable with older npm versions.

1014 +Ideal if all users are on npm version 7 and higher.

1015 +

1016 +<!-- automatically generated, do not edit manually -->

1017 +<!-- see lib/utils/config/definitions.js -->

1018 +

1019 +#### `loglevel`

1020 +

1021 +* Default: "notice"

1022 +* Type: "silent", "error", "warn", "notice", "http", "timing", "info",

1023 + "verbose", or "silly"

1024 +

1025 +What level of logs to report. On failure, *all* logs are written to

1026 +`npm-debug.log` in the current working directory.

1027 +

1028 +Any logs of a higher level than the setting are shown. The default is

1029 +"notice".

1030 +

1031 +See also the `foreground-scripts` config.

1032 +

1033 +<!-- automatically generated, do not edit manually -->

1034 +<!-- see lib/utils/config/definitions.js -->

1035 +

1036 +#### `logs-max`

1037 +

1038 +* Default: 10

1039 +* Type: Number

1040 +

1041 +The maximum number of log files to store.

1042 +

1043 +<!-- automatically generated, do not edit manually -->

1044 +<!-- see lib/utils/config/definitions.js -->

1045 +

1046 +#### `long`

1047 +

1048 +* Default: false

1049 +* Type: Boolean

1050 +

1051 +Show extended information in `ls`, `search`, and `help-search`.

1052 +

1053 +<!-- automatically generated, do not edit manually -->

1054 +<!-- see lib/utils/config/definitions.js -->

1055 +

1056 +#### `maxsockets`

1057 +

1058 +* Default: 15

1059 +* Type: Number

1060 +

1061 +The maximum number of connections to use per origin (protocol/host/port

1062 +combination).

1063 +

1064 +<!-- automatically generated, do not edit manually -->

1065 +<!-- see lib/utils/config/definitions.js -->

1066 +

1067 +#### `message`

1068 +

1069 +* Default: "%s"

1070 +* Type: String

1071 +

1072 +Commit message which is used by `npm version` when creating version commit.

1073 +

1074 +Any "%s" in the message will be replaced with the version number.

1075 +

1076 +<!-- automatically generated, do not edit manually -->

1077 +<!-- see lib/utils/config/definitions.js -->

1078 +

1079 +#### `node-options`

1080 +

1081 +* Default: null

1082 +* Type: null or String

1083 +

1084 +Options to pass through to Node.js via the `NODE_OPTIONS` environment

1085 +variable. This does not impact how npm itself is executed but it does impact

1086 +how lifecycle scripts are called.

1087 +

1088 +<!-- automatically generated, do not edit manually -->

1089 +<!-- see lib/utils/config/definitions.js -->

1090 +

1091 +#### `node-version`

1092 +

1093 +* Default: Node.js `process.version` value

1094 +* Type: SemVer string

1095 +

1096 +The node version to use when checking a package's `engines` setting.

1097 +

1098 +<!-- automatically generated, do not edit manually -->

1099 +<!-- see lib/utils/config/definitions.js -->

1100 +

1101 +#### `noproxy`

1102 +

1103 +* Default: The value of the NO_PROXY environment variable

1104 +* Type: String (can be set multiple times)

1105 +

1106 +Domain extensions that should bypass any proxies.

1107 +

1108 +Also accepts a comma-delimited string.

1109 +

1110 +<!-- automatically generated, do not edit manually -->

1111 +<!-- see lib/utils/config/definitions.js -->

1112 +

1113 +#### `npm-version`

1114 +

1115 +* Default: Output of `npm --version`

1116 +* Type: SemVer string

1117 +

1118 +The npm version to use when checking a package's `engines` setting.

1119 +

1120 +<!-- automatically generated, do not edit manually -->

1121 +<!-- see lib/utils/config/definitions.js -->

1122 +

1123 +#### `offline`

1124 +

1125 +* Default: false

1126 +* Type: Boolean

1127 +

1128 +Force offline mode: no network requests will be done during install. To

1129 +allow the CLI to fill in missing cache data, see `--prefer-offline`.

1130 +

1131 +<!-- automatically generated, do not edit manually -->

1132 +<!-- see lib/utils/config/definitions.js -->

1133 +

1134 +#### `omit`

1135 +

1136 +* Default: 'dev' if the `NODE_ENV` environment variable is set to

1137 + 'production', otherwise empty.

1138 +* Type: "dev", "optional", or "peer" (can be set multiple times)

1139 +

1140 +Dependency types to omit from the installation tree on disk.

1141 +

1142 +Note that these dependencies _are_ still resolved and added to the

1143 +`package-lock.json` or `npm-shrinkwrap.json` file. They are just not

1144 +physically installed on disk.

1145 +

1146 +If a package type appears in both the `--include` and `--omit` lists, then

1147 +it will be included.

1148 +

1149 +If the resulting omit list includes `'dev'`, then the `NODE_ENV` environment

1150 +variable will be set to `'production'` for all lifecycle scripts.

1151 +

1152 +<!-- automatically generated, do not edit manually -->

1153 +<!-- see lib/utils/config/definitions.js -->

1154 +

1155 +#### `otp`

1156 +

1157 +* Default: null

1158 +* Type: null or String

1159 +

1160 +This is a one-time password from a two-factor authenticator. It's needed

1161 +when publishing or changing package permissions with `npm access`.

1162 +

1163 +If not set, and a registry response fails with a challenge for a one-time

1164 +password, npm will prompt on the command line for one.

1165 +

1166 +<!-- automatically generated, do not edit manually -->

1167 +<!-- see lib/utils/config/definitions.js -->

1168 +

1169 +#### `pack-destination`

1170 +

1171 +* Default: "."

1172 +* Type: String

1173 +

1174 +Directory in which `npm pack` will save tarballs.

1175 +

1176 +<!-- automatically generated, do not edit manually -->

1177 +<!-- see lib/utils/config/definitions.js -->

1178 +

1179 +#### `package`

1180 +

1181 +* Default:

1182 +* Type: String (can be set multiple times)

1183 +

1184 +The package to install for [`npm exec`](/cli/v8/commands/npm-exec)

1185 +

1186 +<!-- automatically generated, do not edit manually -->

1187 +<!-- see lib/utils/config/definitions.js -->

1188 +

1189 +#### `package-lock`

1190 +

1191 +* Default: true

1192 +* Type: Boolean

1193 +

1194 +If set to false, then ignore `package-lock.json` files when installing. This

1195 +will also prevent _writing_ `package-lock.json` if `save` is true.

1196 +

1197 +When package package-locks are disabled, automatic pruning of extraneous

1198 +modules will also be disabled. To remove extraneous modules with

1199 +package-locks disabled use `npm prune`.

1200 +

1201 +<!-- automatically generated, do not edit manually -->

1202 +<!-- see lib/utils/config/definitions.js -->

1203 +

1204 +#### `package-lock-only`

1205 +

1206 +* Default: false

1207 +* Type: Boolean

1208 +

1209 +If set to true, the current operation will only use the `package-lock.json`,

1210 +ignoring `node_modules`.

1211 +

1212 +For `update` this means only the `package-lock.json` will be updated,

1213 +instead of checking `node_modules` and downloading dependencies.

1214 +

1215 +For `list` this means the output will be based on the tree described by the

1216 +`package-lock.json`, rather than the contents of `node_modules`.

1217 +

1218 +<!-- automatically generated, do not edit manually -->

1219 +<!-- see lib/utils/config/definitions.js -->

1220 +

1221 +#### `parseable`

1222 +

1223 +* Default: false

1224 +* Type: Boolean

1225 +

1226 +Output parseable results from commands that write to standard output. For

1227 +`npm search`, this will be tab-separated table format.

1228 +

1229 +<!-- automatically generated, do not edit manually -->

1230 +<!-- see lib/utils/config/definitions.js -->

1231 +

1232 +#### `prefer-offline`

1233 +

1234 +* Default: false

1235 +* Type: Boolean

1236 +

1237 +If true, staleness checks for cached data will be bypassed, but missing data

1238 +will be requested from the server. To force full offline mode, use

1239 +`--offline`.

1240 +

1241 +<!-- automatically generated, do not edit manually -->

1242 +<!-- see lib/utils/config/definitions.js -->

1243 +

1244 +#### `prefer-online`

1245 +

1246 +* Default: false

1247 +* Type: Boolean

1248 +

1249 +If true, staleness checks for cached data will be forced, making the CLI

1250 +look for updates immediately even for fresh package data.

1251 +

1252 +<!-- automatically generated, do not edit manually -->

1253 +<!-- see lib/utils/config/definitions.js -->

1254 +

1255 +#### `prefix`

1256 +

1257 +* Default: In global mode, the folder where the node executable is installed.

1258 + In local mode, the nearest parent folder containing either a package.json

1259 + file or a node_modules folder.

1260 +* Type: Path

1261 +

1262 +The location to install global items. If set on the command line, then it

1263 +forces non-global commands to run in the specified folder.

1264 +

1265 +<!-- automatically generated, do not edit manually -->

1266 +<!-- see lib/utils/config/definitions.js -->

1267 +

1268 +#### `preid`

1269 +

1270 +* Default: ""

1271 +* Type: String

1272 +

1273 +The "prerelease identifier" to use as a prefix for the "prerelease" part of

1274 +a semver. Like the `rc` in `1.2.0-rc.8`.

1275 +

1276 +<!-- automatically generated, do not edit manually -->

1277 +<!-- see lib/utils/config/definitions.js -->

1278 +

1279 +#### `progress`

1280 +

1281 +* Default: `true` unless running in a known CI system

1282 +* Type: Boolean

1283 +

1284 +When set to `true`, npm will display a progress bar during time intensive

1285 +operations, if `process.stderr` is a TTY.

1286 +

1287 +Set to `false` to suppress the progress bar.

1288 +

1289 +<!-- automatically generated, do not edit manually -->

1290 +<!-- see lib/utils/config/definitions.js -->

1291 +

1292 +#### `proxy`

1293 +

1294 +* Default: null

1295 +* Type: null, false, or URL

1296 +

1297 +A proxy to use for outgoing http requests. If the `HTTP_PROXY` or

1298 +`http_proxy` environment variables are set, proxy settings will be honored

1299 +by the underlying `request` library.

1300 +

1301 +<!-- automatically generated, do not edit manually -->

1302 +<!-- see lib/utils/config/definitions.js -->

1303 +

1304 +#### `read-only`

1305 +

1306 +* Default: false

1307 +* Type: Boolean

1308 +

1309 +This is used to mark a token as unable to publish when configuring limited

1310 +access tokens with the `npm token create` command.

1311 +

1312 +<!-- automatically generated, do not edit manually -->

1313 +<!-- see lib/utils/config/definitions.js -->

1314 +

1315 +#### `rebuild-bundle`

1316 +

1317 +* Default: true

1318 +* Type: Boolean

1319 +

1320 +Rebuild bundled dependencies after installation.

1321 +

1322 +<!-- automatically generated, do not edit manually -->

1323 +<!-- see lib/utils/config/definitions.js -->

1324 +

1325 +#### `registry`

1326 +

1327 +* Default: "https://registry.npmjs.org/"

1328 +* Type: URL

1329 +

1330 +The base URL of the npm registry.

1331 +

1332 +<!-- automatically generated, do not edit manually -->

1333 +<!-- see lib/utils/config/definitions.js -->

1334 +

1335 +#### `save`

1336 +

1337 +* Default: true

1338 +* Type: Boolean

1339 +

1340 +Save installed packages to a package.json file as dependencies.

1341 +

1342 +When used with the `npm rm` command, removes the dependency from

1343 +package.json.

1344 +

1345 +<!-- automatically generated, do not edit manually -->

1346 +<!-- see lib/utils/config/definitions.js -->

1347 +

1348 +#### `save-bundle`

1349 +

1350 +* Default: false

1351 +* Type: Boolean

1352 +

1353 +If a package would be saved at install time by the use of `--save`,

1354 +`--save-dev`, or `--save-optional`, then also put it in the

1355 +`bundleDependencies` list.

1356 +

1357 +Ignore if `--save-peer` is set, since peerDependencies cannot be bundled.

1358 +

1359 +<!-- automatically generated, do not edit manually -->

1360 +<!-- see lib/utils/config/definitions.js -->

1361 +

1362 +#### `save-dev`

1363 +

1364 +* Default: false

1365 +* Type: Boolean

1366 +

1367 +Save installed packages to a package.json file as `devDependencies`.

1368 +

1369 +<!-- automatically generated, do not edit manually -->

1370 +<!-- see lib/utils/config/definitions.js -->

1371 +

1372 +#### `save-exact`

1373 +

1374 +* Default: false

1375 +* Type: Boolean

1376 +

1377 +Dependencies saved to package.json will be configured with an exact version

1378 +rather than using npm's default semver range operator.

1379 +

1380 +<!-- automatically generated, do not edit manually -->

1381 +<!-- see lib/utils/config/definitions.js -->

1382 +

1383 +#### `save-optional`

1384 +

1385 +* Default: false

1386 +* Type: Boolean

1387 +

1388 +Save installed packages to a package.json file as `optionalDependencies`.

1389 +

1390 +<!-- automatically generated, do not edit manually -->

1391 +<!-- see lib/utils/config/definitions.js -->

1392 +

1393 +#### `save-peer`

1394 +

1395 +* Default: false

1396 +* Type: Boolean

1397 +

1398 +Save installed packages. to a package.json file as `peerDependencies`

1399 +

1400 +<!-- automatically generated, do not edit manually -->

1401 +<!-- see lib/utils/config/definitions.js -->

1402 +

1403 +#### `save-prefix`

1404 +

1405 +* Default: "^"

1406 +* Type: String

1407 +

1408 +Configure how versions of packages installed to a package.json file via

1409 +`--save` or `--save-dev` get prefixed.

1410 +

1411 +For example if a package has version `1.2.3`, by default its version is set

1412 +to `^1.2.3` which allows minor upgrades for that package, but after `npm

1413 +config set save-prefix='~'` it would be set to `~1.2.3` which only allows

1414 +patch upgrades.

1415 +

1416 +<!-- automatically generated, do not edit manually -->

1417 +<!-- see lib/utils/config/definitions.js -->

1418 +

1419 +#### `save-prod`

1420 +

1421 +* Default: false

1422 +* Type: Boolean

1423 +

1424 +Save installed packages into `dependencies` specifically. This is useful if

1425 +a package already exists in `devDependencies` or `optionalDependencies`, but

1426 +you want to move it to be a non-optional production dependency.

1427 +

1428 +This is the default behavior if `--save` is true, and neither `--save-dev`

1429 +or `--save-optional` are true.

1430 +

1431 +<!-- automatically generated, do not edit manually -->

1432 +<!-- see lib/utils/config/definitions.js -->

1433 +

1434 +#### `scope`

1435 +

1436 +* Default: the scope of the current project, if any, or ""

1437 +* Type: String

1438 +

1439 +Associate an operation with a scope for a scoped registry.

1440 +

1441 +Useful when logging in to or out of a private registry:

1442 +

1443 +```

1444 +# log in, linking the scope to the custom registry

1445 +npm login --scope=@mycorp --registry=https://registry.mycorp.com

1446 +

1447 +# log out, removing the link and the auth token

1448 +npm logout --scope=@mycorp

1449 +```

1450 +

1451 +This will cause `@mycorp` to be mapped to the registry for future

1452 +installation of packages specified according to the pattern

1453 +`@mycorp/package`.

1454 +

1455 +This will also cause `npm init` to create a scoped package.

1456 +

1457 +```

1458 +# accept all defaults, and create a package named "@foo/whatever",

1459 +# instead of just named "whatever"

1460 +npm init --scope=@foo --yes

1461 +```

1462 +

1463 +

1464 +<!-- automatically generated, do not edit manually -->

1465 +<!-- see lib/utils/config/definitions.js -->

1466 +

1467 +#### `script-shell`

1468 +

1469 +* Default: '/bin/sh' on POSIX systems, 'cmd.exe' on Windows

1470 +* Type: null or String

1471 +

1472 +The shell to use for scripts run with the `npm exec`, `npm run` and `npm

1473 +init <pkg>` commands.

1474 +

1475 +<!-- automatically generated, do not edit manually -->

1476 +<!-- see lib/utils/config/definitions.js -->

1477 +

1478 +#### `searchexclude`

1479 +

1480 +* Default: ""

1481 +* Type: String

1482 +

1483 +Space-separated options that limit the results from search.

1484 +

1485 +<!-- automatically generated, do not edit manually -->

1486 +<!-- see lib/utils/config/definitions.js -->

1487 +

1488 +#### `searchlimit`

1489 +

1490 +* Default: 20

1491 +* Type: Number

1492 +

1493 +Number of items to limit search results to. Will not apply at all to legacy

1494 +searches.

1495 +

1496 +<!-- automatically generated, do not edit manually -->

1497 +<!-- see lib/utils/config/definitions.js -->

1498 +

1499 +#### `searchopts`

1500 +

1501 +* Default: ""

1502 +* Type: String

1503 +

1504 +Space-separated options that are always passed to search.

1505 +

1506 +<!-- automatically generated, do not edit manually -->

1507 +<!-- see lib/utils/config/definitions.js -->

1508 +

1509 +#### `searchstaleness`

1510 +

1511 +* Default: 900

1512 +* Type: Number

1513 +

1514 +The age of the cache, in seconds, before another registry request is made if

1515 +using legacy search endpoint.

1516 +

1517 +<!-- automatically generated, do not edit manually -->

1518 +<!-- see lib/utils/config/definitions.js -->

1519 +

1520 +#### `shell`

1521 +

1522 +* Default: SHELL environment variable, or "bash" on Posix, or "cmd.exe" on

1523 + Windows

1524 +* Type: String

1525 +

1526 +The shell to run for the `npm explore` command.

1527 +

1528 +<!-- automatically generated, do not edit manually -->

1529 +<!-- see lib/utils/config/definitions.js -->

1530 +

1531 +#### `sign-git-commit`

1532 +

1533 +* Default: false

1534 +* Type: Boolean

1535 +

1536 +If set to true, then the `npm version` command will commit the new package

1537 +version using `-S` to add a signature.

1538 +

1539 +Note that git requires you to have set up GPG keys in your git configs for

1540 +this to work properly.

1541 +

1542 +<!-- automatically generated, do not edit manually -->

1543 +<!-- see lib/utils/config/definitions.js -->

1544 +

1545 +#### `sign-git-tag`

1546 +

1547 +* Default: false

1548 +* Type: Boolean

1549 +

1550 +If set to true, then the `npm version` command will tag the version using

1551 +`-s` to add a signature.

1552 +

1553 +Note that git requires you to have set up GPG keys in your git configs for

1554 +this to work properly.

1555 +

1556 +<!-- automatically generated, do not edit manually -->

1557 +<!-- see lib/utils/config/definitions.js -->

1558 +

1559 +#### `strict-peer-deps`

1560 +

1561 +* Default: false

1562 +* Type: Boolean

1563 +

1564 +If set to `true`, and `--legacy-peer-deps` is not set, then _any_

1565 +conflicting `peerDependencies` will be treated as an install failure, even

1566 +if npm could reasonably guess the appropriate resolution based on non-peer

1567 +dependency relationships.

1568 +

1569 +By default, conflicting `peerDependencies` deep in the dependency graph will

1570 +be resolved using the nearest non-peer dependency specification, even if

1571 +doing so will result in some packages receiving a peer dependency outside

1572 +the range set in their package's `peerDependencies` object.

1573 +

1574 +When such and override is performed, a warning is printed, explaining the

1575 +conflict and the packages involved. If `--strict-peer-deps` is set, then

1576 +this warning is treated as a failure.

1577 +

1578 +<!-- automatically generated, do not edit manually -->

1579 +<!-- see lib/utils/config/definitions.js -->

1580 +

1581 +#### `strict-ssl`

1582 +

1583 +* Default: true

1584 +* Type: Boolean

1585 +

1586 +Whether or not to do SSL key validation when making requests to the registry

1587 +via https.

1588 +

1589 +See also the `ca` config.

1590 +

1591 +<!-- automatically generated, do not edit manually -->

1592 +<!-- see lib/utils/config/definitions.js -->

1593 +

1594 +#### `tag`

1595 +

1596 +* Default: "latest"

1597 +* Type: String

1598 +

1599 +If you ask npm to install a package and don't tell it a specific version,

1600 +then it will install the specified tag.

1601 +

1602 +Also the tag that is added to the package@version specified by the `npm tag`

1603 +command, if no explicit tag is given.

1604 +

1605 +When used by the `npm diff` command, this is the tag used to fetch the

1606 +tarball that will be compared with the local files by default.

1607 +

1608 +<!-- automatically generated, do not edit manually -->

1609 +<!-- see lib/utils/config/definitions.js -->

1610 +

1611 +#### `tag-version-prefix`

1612 +

1613 +* Default: "v"

1614 +* Type: String

1615 +

1616 +If set, alters the prefix used when tagging a new version when performing a

1617 +version increment using `npm-version`. To remove the prefix altogether, set

1618 +it to the empty string: `""`.

1619 +

1620 +Because other tools may rely on the convention that npm version tags look

1621 +like `v1.0.0`, _only use this property if it is absolutely necessary_. In

1622 +particular, use care when overriding this setting for public packages.

1623 +

1624 +<!-- automatically generated, do not edit manually -->

1625 +<!-- see lib/utils/config/definitions.js -->

1626 +

1627 +#### `timing`

1628 +

1629 +* Default: false

1630 +* Type: Boolean

1631 +

1632 +If true, writes an `npm-debug` log to `_logs` and timing information to

1633 +`_timing.json`, both in your cache, even if the command completes

1634 +successfully. `_timing.json` is a newline delimited list of JSON objects.

1635 +

1636 +You can quickly view it with this [json](https://npm.im/json) command line:

1637 +`npm exec -- json -g < ~/.npm/_timing.json`.

1638 +

1639 +<!-- automatically generated, do not edit manually -->

1640 +<!-- see lib/utils/config/definitions.js -->

1641 +

1642 +#### `umask`

1643 +

1644 +* Default: 0

1645 +* Type: Octal numeric string in range 0000..0777 (0..511)

1646 +

1647 +The "umask" value to use when setting the file creation mode on files and

1648 +folders.

1649 +

1650 +Folders and executables are given a mode which is `0o777` masked against

1651 +this value. Other files are given a mode which is `0o666` masked against

1652 +this value.

1653 +

1654 +Note that the underlying system will _also_ apply its own umask value to

1655 +files and folders that are created, and npm does not circumvent this, but

1656 +rather adds the `--umask` config to it.

1657 +

1658 +Thus, the effective default umask value on most POSIX systems is 0o22,

1659 +meaning that folders and executables are created with a mode of 0o755 and

1660 +other files are created with a mode of 0o644.

1661 +

1662 +<!-- automatically generated, do not edit manually -->

1663 +<!-- see lib/utils/config/definitions.js -->

1664 +

1665 +#### `unicode`

1666 +

1667 +* Default: false on windows, true on mac/unix systems with a unicode locale,

1668 + as defined by the `LC_ALL`, `LC_CTYPE`, or `LANG` environment variables.

1669 +* Type: Boolean

1670 +

1671 +When set to true, npm uses unicode characters in the tree output. When

1672 +false, it uses ascii characters instead of unicode glyphs.

1673 +

1674 +<!-- automatically generated, do not edit manually -->

1675 +<!-- see lib/utils/config/definitions.js -->

1676 +

1677 +#### `update-notifier`

1678 +

1679 +* Default: true

1680 +* Type: Boolean

1681 +

1682 +Set to false to suppress the update notification when using an older version

1683 +of npm than the latest.

1684 +

1685 +<!-- automatically generated, do not edit manually -->

1686 +<!-- see lib/utils/config/definitions.js -->

1687 +

1688 +#### `usage`

1689 +

1690 +* Default: false

1691 +* Type: Boolean

1692 +

1693 +Show short usage output about the command specified.

1694 +

1695 +<!-- automatically generated, do not edit manually -->

1696 +<!-- see lib/utils/config/definitions.js -->

1697 +

1698 +#### `user-agent`

1699 +

1700 +* Default: "npm/{npm-version} node/{node-version} {platform} {arch}

1701 + workspaces/{workspaces} {ci}"

1702 +* Type: String

1703 +

1704 +Sets the User-Agent request header. The following fields are replaced with

1705 +their actual counterparts:

1706 +

1707 +* `{npm-version}` - The npm version in use

1708 +* `{node-version}` - The Node.js version in use

1709 +* `{platform}` - The value of `process.platform`

1710 +* `{arch}` - The value of `process.arch`

1711 +* `{workspaces}` - Set to `true` if the `workspaces` or `workspace` options

1712 + are set.

1713 +* `{ci}` - The value of the `ci-name` config, if set, prefixed with `ci/`, or

1714 + an empty string if `ci-name` is empty.

1715 +

1716 +<!-- automatically generated, do not edit manually -->

1717 +<!-- see lib/utils/config/definitions.js -->

1718 +

1719 +#### `userconfig`

1720 +

1721 +* Default: "~/.npmrc"

1722 +* Type: Path

1723 +

1724 +The location of user-level configuration settings.

1725 +

1726 +This may be overridden by the `npm_config_userconfig` environment variable

1727 +or the `--userconfig` command line option, but may _not_ be overridden by

1728 +settings in the `globalconfig` file.

1729 +

1730 +<!-- automatically generated, do not edit manually -->

1731 +<!-- see lib/utils/config/definitions.js -->

1732 +

1733 +#### `version`

1734 +

1735 +* Default: false

1736 +* Type: Boolean

1737 +

1738 +If true, output the npm version and exit successfully.

1739 +

1740 +Only relevant when specified explicitly on the command line.

1741 +

1742 +<!-- automatically generated, do not edit manually -->

1743 +<!-- see lib/utils/config/definitions.js -->

1744 +

1745 +#### `versions`

1746 +

1747 +* Default: false

1748 +* Type: Boolean

1749 +

1750 +If true, output the npm version as well as node's `process.versions` map and

1751 +the version in the current working directory's `package.json` file if one

1752 +exists, and exit successfully.

1753 +

1754 +Only relevant when specified explicitly on the command line.

1755 +

1756 +<!-- automatically generated, do not edit manually -->

1757 +<!-- see lib/utils/config/definitions.js -->

1758 +

1759 +#### `viewer`

1760 +

1761 +* Default: "man" on Posix, "browser" on Windows

1762 +* Type: String

1763 +

1764 +The program to use to view help content.

1765 +

1766 +Set to `"browser"` to view html help content in the default web browser.

1767 +

1768 +<!-- automatically generated, do not edit manually -->

1769 +<!-- see lib/utils/config/definitions.js -->

1770 +

1771 +#### `which`

1772 +

1773 +* Default: null

1774 +* Type: null or Number

1775 +

1776 +If there are multiple funding sources, which 1-indexed source URL to open.

1777 +

1778 +<!-- automatically generated, do not edit manually -->

1779 +<!-- see lib/utils/config/definitions.js -->

1780 +

1781 +#### `workspace`

1782 +

1783 +* Default:

1784 +* Type: String (can be set multiple times)

1785 +

1786 +Enable running a command in the context of the configured workspaces of the

1787 +current project while filtering by running only the workspaces defined by

1788 +this configuration option.

1789 +

1790 +Valid values for the `workspace` config are either:

1791 +

1792 +* Workspace names

1793 +* Path to a workspace directory

1794 +* Path to a parent workspace directory (will result in selecting all

1795 + workspaces within that folder)

1796 +

1797 +When set for the `npm init` command, this may be set to the folder of a

1798 +workspace which does not yet exist, to create the folder and set it up as a

1799 +brand new workspace within the project.

1800 +

1801 +This value is not exported to the environment for child processes.

1802 +

1803 +<!-- automatically generated, do not edit manually -->

1804 +<!-- see lib/utils/config/definitions.js -->

1805 +

1806 +#### `workspaces`

1807 +

1808 +* Default: null

1809 +* Type: null or Boolean

1810 +

1811 +Set to true to run the command in the context of **all** configured

1812 +workspaces.

1813 +

1814 +Explicitly setting this to false will cause commands like `install` to

1815 +ignore workspaces altogether. When not set explicitly:

1816 +

1817 +- Commands that operate on the `node_modules` tree (install, update, etc.)

1818 +will link workspaces into the `node_modules` folder. - Commands that do

1819 +other things (test, exec, publish, etc.) will operate on the root project,

1820 +_unless_ one or more workspaces are specified in the `workspace` config.

1821 +

1822 +This value is not exported to the environment for child processes.

1823 +

1824 +<!-- automatically generated, do not edit manually -->

1825 +<!-- see lib/utils/config/definitions.js -->

1826 +

1827 +#### `yes`

1828 +

1829 +* Default: null

1830 +* Type: null or Boolean

1831 +

1832 +Automatically answer "yes" to any prompts that npm might print on the

1833 +command line.

1834 +

1835 +<!-- automatically generated, do not edit manually -->

1836 +<!-- see lib/utils/config/definitions.js -->

1837 +

1838 +#### `also`

1839 +

1840 +* Default: null

1841 +* Type: null, "dev", or "development"

1842 +* DEPRECATED: Please use --include=dev instead.

1843 +

1844 +When set to `dev` or `development`, this is an alias for `--include=dev`.

1845 +

1846 +<!-- automatically generated, do not edit manually -->

1847 +<!-- see lib/utils/config/definitions.js -->

1848 +

1849 +#### `auth-type`

1850 +

1851 +* Default: "legacy"

1852 +* Type: "legacy", "sso", "saml", or "oauth"

1853 +* DEPRECATED: This method of SSO/SAML/OAuth is deprecated and will be removed

1854 + in a future version of npm in favor of web-based login.

1855 +

1856 +What authentication strategy to use with `adduser`/`login`.

1857 +

1858 +<!-- automatically generated, do not edit manually -->

1859 +<!-- see lib/utils/config/definitions.js -->

1860 +

1861 +#### `cache-max`

1862 +

1863 +* Default: Infinity

1864 +* Type: Number

1865 +* DEPRECATED: This option has been deprecated in favor of `--prefer-online`

1866 +

1867 +`--cache-max=0` is an alias for `--prefer-online`

1868 +

1869 +<!-- automatically generated, do not edit manually -->

1870 +<!-- see lib/utils/config/definitions.js -->

1871 +

1872 +#### `cache-min`

1873 +

1874 +* Default: 0

1875 +* Type: Number

1876 +* DEPRECATED: This option has been deprecated in favor of `--prefer-offline`.

1877 +

1878 +`--cache-min=9999 (or bigger)` is an alias for `--prefer-offline`.

1879 +

1880 +<!-- automatically generated, do not edit manually -->

1881 +<!-- see lib/utils/config/definitions.js -->

1882 +

1883 +#### `dev`

1884 +

1885 +* Default: false

1886 +* Type: Boolean

1887 +* DEPRECATED: Please use --include=dev instead.

1888 +

1889 +Alias for `--include=dev`.

1890 +

1891 +<!-- automatically generated, do not edit manually -->

1892 +<!-- see lib/utils/config/definitions.js -->

1893 +

1894 +#### `init.author.email`

1895 +

1896 +* Default: ""

1897 +* Type: String

1898 +* DEPRECATED: Use `--init-author-email` instead.

1899 +

1900 +Alias for `--init-author-email`

1901 +

1902 +<!-- automatically generated, do not edit manually -->

1903 +<!-- see lib/utils/config/definitions.js -->

1904 +

1905 +#### `init.author.name`

1906 +

1907 +* Default: ""

1908 +* Type: String

1909 +* DEPRECATED: Use `--init-author-name` instead.

1910 +

1911 +Alias for `--init-author-name`

1912 +

1913 +<!-- automatically generated, do not edit manually -->

1914 +<!-- see lib/utils/config/definitions.js -->

1915 +

1916 +#### `init.author.url`

1917 +

1918 +* Default: ""

1919 +* Type: "" or URL

1920 +* DEPRECATED: Use `--init-author-url` instead.

1921 +

1922 +Alias for `--init-author-url`

1923 +

1924 +<!-- automatically generated, do not edit manually -->

1925 +<!-- see lib/utils/config/definitions.js -->

1926 +

1927 +#### `init.license`

1928 +

1929 +* Default: "ISC"

1930 +* Type: String

1931 +* DEPRECATED: Use `--init-license` instead.

1932 +

1933 +Alias for `--init-license`

1934 +

1935 +<!-- automatically generated, do not edit manually -->

1936 +<!-- see lib/utils/config/definitions.js -->

1937 +

1938 +#### `init.module`

1939 +

1940 +* Default: "~/.npm-init.js"

1941 +* Type: Path

1942 +* DEPRECATED: Use `--init-module` instead.

1943 +

1944 +Alias for `--init-module`

1945 +

1946 +<!-- automatically generated, do not edit manually -->

1947 +<!-- see lib/utils/config/definitions.js -->

1948 +

1949 +#### `init.version`

1950 +

1951 +* Default: "1.0.0"

1952 +* Type: SemVer string

1953 +* DEPRECATED: Use `--init-version` instead.

1954 +

1955 +Alias for `--init-version`

1956 +

1957 +<!-- automatically generated, do not edit manually -->

1958 +<!-- see lib/utils/config/definitions.js -->

1959 +

1960 +#### `only`

1961 +

1962 +* Default: null

1963 +* Type: null, "prod", or "production"

1964 +* DEPRECATED: Use `--omit=dev` to omit dev dependencies from the install.

1965 +

1966 +When set to `prod` or `production`, this is an alias for `--omit=dev`.

1967 +

1968 +<!-- automatically generated, do not edit manually -->

1969 +<!-- see lib/utils/config/definitions.js -->

1970 +

1971 +#### `optional`

1972 +

1973 +* Default: null

1974 +* Type: null or Boolean

1975 +* DEPRECATED: Use `--omit=optional` to exclude optional dependencies, or

1976 + `--include=optional` to include them.

1977 +

1978 +Default value does install optional deps unless otherwise omitted.

1979 +

1980 +Alias for --include=optional or --omit=optional

1981 +

1982 +<!-- automatically generated, do not edit manually -->

1983 +<!-- see lib/utils/config/definitions.js -->

1984 +

1985 +#### `production`

1986 +

1987 +* Default: null

1988 +* Type: null or Boolean

1989 +* DEPRECATED: Use `--omit=dev` instead.

1990 +

1991 +Alias for `--omit=dev`

1992 +

1993 +<!-- automatically generated, do not edit manually -->

1994 +<!-- see lib/utils/config/definitions.js -->

1995 +

1996 +#### `shrinkwrap`

1997 +

1998 +* Default: true

1999 +* Type: Boolean

2000 +* DEPRECATED: Use the --package-lock setting instead.

2001 +

2002 +Alias for --package-lock

2003 +

2004 +<!-- automatically generated, do not edit manually -->

2005 +<!-- see lib/utils/config/definitions.js -->

2006 +

2007 +#### `sso-poll-frequency`

2008 +

2009 +* Default: 500

2010 +* Type: Number

2011 +* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a

2012 + future version of npm in favor of web-based login.

2013 +

2014 +When used with SSO-enabled `auth-type`s, configures how regularly the

2015 +registry should be polled while the user is completing authentication.

2016 +

2017 +<!-- automatically generated, do not edit manually -->

2018 +<!-- see lib/utils/config/definitions.js -->

2019 +

2020 +#### `sso-type`

2021 +

2022 +* Default: "oauth"

2023 +* Type: null, "oauth", or "saml"

2024 +* DEPRECATED: The --auth-type method of SSO/SAML/OAuth will be removed in a

2025 + future version of npm in favor of web-based login.

2026 +

2027 +If `--auth-type=sso`, the type of SSO type to use.

2028 +

2029 +<!-- automatically generated, do not edit manually -->

2030 +<!-- see lib/utils/config/definitions.js -->

2031 +

2032 +#### `tmp`

2033 +

2034 +* Default: The value returned by the Node.js `os.tmpdir()` method

2035 + <https://nodejs.org/api/os.html#os_os_tmpdir>

2036 +* Type: Path

2037 +* DEPRECATED: This setting is no longer used. npm stores temporary files in a

2038 + special location in the cache, and they are managed by

2039 + [`cacache`](http://npm.im/cacache).

2040 +

2041 +Historically, the location where temporary files were stored. No longer

2042 +relevant.

2043 +

2044 +<!-- automatically generated, do not edit manually -->

2045 +<!-- see lib/utils/config/definitions.js -->

2046 +<!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->

2047 +

2048 +### See also

2049 +

2050 +* [npm config](/cli/v8/commands/npm-config)

2051 +* [npmrc](/cli/v8/configuring-npm/npmrc)

2052 +* [npm scripts](/cli/v8/using-npm/scripts)

2053 +* [npm folders](/cli/v8/configuring-npm/folders)

2054 +* [npm](/cli/v8/commands/npm)

content/cli/v8/using-npm/developers.md new

+251

@@ -0,0 +1,251 @@

1 +---

2 +title: developers

3 +section: 7

4 +description: Developer Guide

5 +redirect_from:

6 + - /using-npm/developers

7 + - /using-npm/developers.html

8 + - /misc/developers

9 + - /misc/developers.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/developers.md

13 +---

14 +

15 +### Description

16 +

17 +So, you've decided to use npm to develop (and maybe publish/deploy)

18 +your project.

19 +

20 +Fantastic!

21 +

22 +There are a few things that you need to do above the simple steps

23 +that your users will do to install your program.

24 +

25 +### About These Documents

26 +

27 +These are man pages. If you install npm, you should be able to

28 +then do `man npm-thing` to get the documentation on a particular

29 +topic, or `npm help thing` to see the same information.

30 +

31 +### What is a Package

32 +

33 +A package is:

34 +

35 +* a) a folder containing a program described by a package.json file

36 +* b) a gzipped tarball containing (a)

37 +* c) a url that resolves to (b)

38 +* d) a `<name>@<version>` that is published on the registry with (c)

39 +* e) a `<name>@<tag>` that points to (d)

40 +* f) a `<name>` that has a "latest" tag satisfying (e)

41 +* g) a `git` url that, when cloned, results in (a).

42 +

43 +Even if you never publish your package, you can still get a lot of

44 +benefits of using npm if you just want to write a node program (a), and

45 +perhaps if you also want to be able to easily install it elsewhere

46 +after packing it up into a tarball (b).

47 +

48 +Git urls can be of the form:

49 +

50 +```bash

51 +git://github.com/user/project.git#commit-ish

52 +git+ssh://user@hostname:project.git#commit-ish

53 +git+http://user@hostname/project/blah.git#commit-ish

54 +git+https://user@hostname/project/blah.git#commit-ish

55 +```

56 +

57 +The `commit-ish` can be any tag, sha, or branch which can be supplied as

58 +an argument to `git checkout`. The default is whatever the repository uses

59 +as its default branch.

60 +

61 +### The package.json File

62 +

63 +You need to have a `package.json` file in the root of your project to do

64 +much of anything with npm. That is basically the whole interface.

65 +

66 +See [`package.json`](/cli/v8/configuring-npm/package-json) for details about what

67 +goes in that file. At the very least, you need:

68 +

69 +* name: This should be a string that identifies your project. Please do

70 + not use the name to specify that it runs on node, or is in JavaScript.

71 + You can use the "engines" field to explicitly state the versions of node

72 + (or whatever else) that your program requires, and it's pretty well

73 + assumed that it's JavaScript.

74 +

75 + It does not necessarily need to match your github repository name.

76 +

77 + So, `node-foo` and `bar-js` are bad names. `foo` or `bar` are better.

78 +

79 +* version: A semver-compatible version.

80 +

81 +* engines: Specify the versions of node (or whatever else) that your

82 + program runs on. The node API changes a lot, and there may be bugs or

83 + new functionality that you depend on. Be explicit.

84 +

85 +* author: Take some credit.

86 +

87 +* scripts: If you have a special compilation or installation script, then

88 + you should put it in the `scripts` object. You should definitely have at

89 + least a basic smoke-test command as the "scripts.test" field. See

90 + [scripts](/cli/v8/using-npm/scripts).

91 +

92 +* main: If you have a single module that serves as the entry point to your

93 + program (like what the "foo" package gives you at require("foo")), then

94 + you need to specify that in the "main" field.

95 +

96 +* directories: This is an object mapping names to folders. The best ones

97 + to include are "lib" and "doc", but if you use "man" to specify a folder

98 + full of man pages, they'll get installed just like these ones.

99 +

100 +You can use `npm init` in the root of your package in order to get you

101 +started with a pretty basic package.json file. See [`npm

102 +init`](/cli/v8/commands/npm-init) for more info.

103 +

104 +### Keeping files *out* of your Package

105 +

106 +Use a `.npmignore` file to keep stuff out of your package. If there's no

107 +`.npmignore` file, but there *is* a `.gitignore` file, then npm will ignore

108 +the stuff matched by the `.gitignore` file. If you *want* to include

109 +something that is excluded by your `.gitignore` file, you can create an

110 +empty `.npmignore` file to override it. Like `git`, `npm` looks for

111 +`.npmignore` and `.gitignore` files in all subdirectories of your package,

112 +not only the root directory.

113 +

114 +`.npmignore` files follow the [same pattern

115 +rules](https://git-scm.com/book/en/v2/Git-Basics-Recording-Changes-to-the-Repository#_ignoring)

116 +as `.gitignore` files:

117 +

118 +* Blank lines or lines starting with `#` are ignored.

119 +* Standard glob patterns work.

120 +* You can end patterns with a forward slash `/` to specify a directory.

121 +* You can negate a pattern by starting it with an exclamation point `!`.

122 +

123 +By default, the following paths and files are ignored, so there's no

124 +need to add them to `.npmignore` explicitly:

125 +

126 +* `.*.swp`

127 +* `._*`

128 +* `.DS_Store`

129 +* `.git`

130 +* `.hg`

131 +* `.npmrc`

132 +* `.lock-wscript`

133 +* `.svn`

134 +* `.wafpickle-*`

135 +* `config.gypi`

136 +* `CVS`

137 +* `npm-debug.log`

138 +

139 +Additionally, everything in `node_modules` is ignored, except for

140 +bundled dependencies. npm automatically handles this for you, so don't

141 +bother adding `node_modules` to `.npmignore`.

142 +

143 +The following paths and files are never ignored, so adding them to

144 +`.npmignore` is pointless:

145 +

146 +* `package.json`

147 +* `README` (and its variants)

148 +* `CHANGELOG` (and its variants)

149 +* `LICENSE` / `LICENCE`

150 +

151 +If, given the structure of your project, you find `.npmignore` to be a

152 +maintenance headache, you might instead try populating the `files`

153 +property of `package.json`, which is an array of file or directory names

154 +that should be included in your package. Sometimes manually picking

155 +which items to allow is easier to manage than building a block list.

156 +

157 +#### Testing whether your `.npmignore` or `files` config works

158 +

159 +If you want to double check that your package will include only the files

160 +you intend it to when published, you can run the `npm pack` command locally

161 +which will generate a tarball in the working directory, the same way it

162 +does for publishing.

163 +

164 +### Link Packages

165 +

166 +`npm link` is designed to install a development package and see the

167 +changes in real time without having to keep re-installing it. (You do

168 +need to either re-link or `npm rebuild -g` to update compiled packages,

169 +of course.)

170 +

171 +More info at [`npm link`](/cli/v8/commands/npm-link).

172 +

173 +### Before Publishing: Make Sure Your Package Installs and Works

174 +

175 +**This is important.**

176 +

177 +If you can not install it locally, you'll have

178 +problems trying to publish it. Or, worse yet, you'll be able to

179 +publish it, but you'll be publishing a broken or pointless package.

180 +So don't do that.

181 +

182 +In the root of your package, do this:

183 +

184 +```bash

185 +npm install . -g

186 +```

187 +

188 +That'll show you that it's working. If you'd rather just create a symlink

189 +package that points to your working directory, then do this:

190 +

191 +```bash

192 +npm link

193 +```

194 +

195 +Use `npm ls -g` to see if it's there.

196 +

197 +To test a local install, go into some other folder, and then do:

198 +

199 +```bash

200 +cd ../some-other-folder

201 +npm install ../my-package

202 +```

203 +

204 +to install it locally into the node_modules folder in that other place.

205 +

206 +Then go into the node-repl, and try using require("my-thing") to

207 +bring in your module's main module.

208 +

209 +### Create a User Account

210 +

211 +Create a user with the adduser command. It works like this:

212 +

213 +```bash

214 +npm adduser

215 +```

216 +

217 +and then follow the prompts.

218 +

219 +This is documented better in [npm adduser](/cli/v8/commands/npm-adduser).

220 +

221 +### Publish your Package

222 +

223 +This part's easy. In the root of your folder, do this:

224 +

225 +```bash

226 +npm publish

227 +```

228 +

229 +You can give publish a url to a tarball, or a filename of a tarball,

230 +or a path to a folder.

231 +

232 +Note that pretty much **everything in that folder will be exposed**

233 +by default. So, if you have secret stuff in there, use a

234 +`.npmignore` file to list out the globs to ignore, or publish

235 +from a fresh checkout.

236 +

237 +### Brag about it

238 +

239 +Send emails, write blogs, blab in IRC.

240 +

241 +Tell the world how easy it is to install your program!

242 +

243 +### See also

244 +

245 +* [npm](/cli/v8/commands/npm)

246 +* [npm init](/cli/v8/commands/npm-init)

247 +* [package.json](/cli/v8/configuring-npm/package-json)

248 +* [npm scripts](/cli/v8/using-npm/scripts)

249 +* [npm publish](/cli/v8/commands/npm-publish)

250 +* [npm adduser](/cli/v8/commands/npm-adduser)

251 +* [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/using-npm/index.mdx new

+13

@@ -0,0 +1,13 @@

1 +---

2 +redirect_from:

3 + - using-npm

4 + - /cli/using-npm

5 + - cli-documentation/misc

6 + - cli-documentation/using-npm

7 + - /misc/index.html

8 +github_repo: npm/cli

9 +github_branch: latest

10 +github_path: docs/content/using-npm/index.mdx

11 +title: Using npm

12 +---

13 +<Index depth="1" />

\ No newline at end of file

content/cli/v8/using-npm/orgs.md new

+101

@@ -0,0 +1,101 @@

1 +---

2 +title: orgs

3 +section: 7

4 +description: Working with Teams & Orgs

5 +redirect_from:

6 + - /using-npm/orgs

7 + - /using-npm/orgs.html

8 + - /misc/orgs

9 + - /misc/orgs.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/orgs.md

13 +---

14 +

15 +### Description

16 +

17 +There are three levels of org users:

18 +

19 +1. Super admin, controls billing & adding people to the org.

20 +2. Team admin, manages team membership & package access.

21 +3. Developer, works on packages they are given access to.

22 +

23 +The super admin is the only person who can add users to the org because it impacts the monthly bill. The super admin will use the website to manage membership. Every org has a `developers` team that all users are automatically added to.

24 +

25 +The team admin is the person who manages team creation, team membership, and package access for teams. The team admin grants package access to teams, not individuals.

26 +

27 +The developer will be able to access packages based on the teams they are on. Access is either read-write or read-only.

28 +

29 +There are two main commands:

30 +

31 +1. `npm team` see [npm team](/cli/v8/commands/npm-team) for more details

32 +2. `npm access` see [npm access](/cli/v8/commands/npm-access) for more details

33 +

34 +### Team Admins create teams

35 +

36 +* Check who you’ve added to your org:

37 +

38 +```bash

39 +npm team ls <org>:developers

40 +```

41 +

42 +* Each org is automatically given a `developers` team, so you can see the whole list of team members in your org. This team automatically gets read-write access to all packages, but you can change that with the `access` command.

43 +

44 +* Create a new team:

45 +

46 +```bash

47 +npm team create <org:team>

48 +```

49 +

50 +* Add members to that team:

51 +

52 +```bash

53 +npm team add <org:team> <user>

54 +```

55 +

56 +### Publish a package and adjust package access

57 +

58 +* In package directory, run

59 +

60 +```bash

61 +npm init --scope=<org>

62 +```

63 +to scope it for your org & publish as usual

64 +

65 +* Grant access:

66 +

67 +```bash

68 +npm access grant <read-only|read-write> <org:team> [<package>]

69 +```

70 +

71 +* Revoke access:

72 +

73 +```bash

74 +npm access revoke <org:team> [<package>]

75 +```

76 +

77 +### Monitor your package access

78 +

79 +* See what org packages a team member can access:

80 +

81 +```bash

82 +npm access ls-packages <org> <user>

83 +```

84 +

85 +* See packages available to a specific team:

86 +

87 +```bash

88 +npm access ls-packages <org:team>

89 +```

90 +

91 +* Check which teams are collaborating on a package:

92 +

93 +```bash

94 +npm access ls-collaborators <pkg>

95 +```

96 +

97 +### See also

98 +

99 +* [npm team](/cli/v8/commands/npm-team)

100 +* [npm access](/cli/v8/commands/npm-access)

101 +* [npm scope](/cli/v8/using-npm/scope)

content/cli/v8/using-npm/registry.md new

+89

@@ -0,0 +1,89 @@

1 +---

2 +title: registry

3 +section: 7

4 +description: The JavaScript Package Registry

5 +redirect_from:

6 + - /using-npm/registry

7 + - /using-npm/registry.html

8 + - /misc/registry

9 + - /misc/registry.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/registry.md

13 +---

14 +

15 +### Description

16 +

17 +To resolve packages by name and version, npm talks to a registry website

18 +that implements the CommonJS Package Registry specification for reading

19 +package info.

20 +

21 +npm is configured to use the **npm public registry** at

22 +<https://registry.npmjs.org> by default. Use of the npm public registry is

23 +subject to terms of use available at <https://docs.npmjs.com/policies/terms>.

24 +

25 +You can configure npm to use any compatible registry you like, and even run

26 +your own registry. Use of someone else's registry may be governed by their

27 +terms of use.

28 +

29 +npm's package registry implementation supports several

30 +write APIs as well, to allow for publishing packages and managing user

31 +account information.

32 +

33 +The npm public registry is powered by a CouchDB database,

34 +of which there is a public mirror at <https://skimdb.npmjs.com/registry>.

35 +

36 +The registry URL used is determined by the scope of the package (see

37 +[`scope`](/cli/v8/using-npm/scope). If no scope is specified, the default registry is used, which is

38 +supplied by the `registry` config parameter. See [`npm config`](/cli/v8/commands/npm-config),

39 +[`npmrc`](/cli/v8/configuring-npm/npmrc), and [`config`](/cli/v8/using-npm/config) for more on managing npm's configuration.

40 +

41 +When the default registry is used in a package-lock or shrinkwrap is has the

42 +special meaning of "the currently configured registry". If you create a lock

43 +file while using the default registry you can switch to another registry and

44 +npm will install packages from the new registry, but if you create a lock

45 +file while using a custom registry packages will be installed from that

46 +registry even after you change to another registry.

47 +

48 +### Does npm send any information about me back to the registry?

49 +

50 +Yes.

51 +

52 +When making requests of the registry npm adds two headers with information

53 +about your environment:

54 +

55 +* `Npm-Scope` – If your project is scoped, this header will contain its

56 + scope. In the future npm hopes to build registry features that use this

57 + information to allow you to customize your experience for your

58 + organization.

59 +* `Npm-In-CI` – Set to "true" if npm believes this install is running in a

60 + continuous integration environment, "false" otherwise. This is detected by

61 + looking for the following environment variables: `CI`, `TDDIUM`,

62 + `JENKINS_URL`, `bamboo.buildKey`. If you'd like to learn more you may find

63 + the [original PR](https://github.com/npm/npm-registry-client/pull/129)

64 + interesting.

65 + This is used to gather better metrics on how npm is used by humans, versus

66 + build farms.

67 +

68 +The npm registry does not try to correlate the information in these headers

69 +with any authenticated accounts that may be used in the same requests.

70 +

71 +### How can I prevent my package from being published in the official registry?

72 +

73 +Set `"private": true` in your `package.json` to prevent it from being

74 +published at all, or

75 +`"publishConfig":{"registry":"http://my-internal-registry.local"}`

76 +to force it to be published only to your internal/private registry.

77 +

78 +See [`package.json`](/cli/v8/configuring-npm/package-json) for more info on what goes in the package.json file.

79 +

80 +### Where can I find my own, & other's, published packages?

81 +

82 +<https://www.npmjs.com/>

83 +

84 +### See also

85 +

86 +* [npm config](/cli/v8/commands/npm-config)

87 +* [config](/cli/v8/using-npm/config)

88 +* [npmrc](/cli/v8/configuring-npm/npmrc)

89 +* [npm developers](/cli/v8/using-npm/developers)

content/cli/v8/using-npm/removal.md new

+74

@@ -0,0 +1,74 @@

1 +---

2 +title: removal

3 +section: 7

4 +description: Cleaning the Slate

5 +redirect_from:

6 + - /using-npm/removal

7 + - /using-npm/removal.html

8 + - /misc/removal

9 + - /misc/removal.html

10 + - /misc/removing-npm

11 + - /misc/removing-npm.html

12 +github_repo: npm/cli

13 +github_branch: latest

14 +github_path: docs/content/using-npm/removal.md

15 +---

16 +

17 +### Synopsis

18 +

19 +So sad to see you go.

20 +

21 +```bash

22 +sudo npm uninstall npm -g

23 +```

24 +

25 +Or, if that fails, get the npm source code, and do:

26 +

27 +```bash

28 +sudo make uninstall

29 +```

30 +

31 +### More Severe Uninstalling

32 +

33 +Usually, the above instructions are sufficient. That will remove

34 +npm, but leave behind anything you've installed.

35 +

36 +If that doesn't work, or if you require more drastic measures,

37 +continue reading.

38 +

39 +Note that this is only necessary for globally-installed packages. Local

40 +installs are completely contained within a project's `node_modules`

41 +folder. Delete that folder, and everything is gone less a package's

42 +install script is particularly ill-behaved).

43 +

44 +This assumes that you installed node and npm in the default place. If

45 +you configured node with a different `--prefix`, or installed npm with a

46 +different prefix setting, then adjust the paths accordingly, replacing

47 +`/usr/local` with your install prefix.

48 +

49 +To remove everything npm-related manually:

50 +

51 +```bash

52 +rm -rf /usr/local/{lib/node{,/.npm,_modules},bin,share/man}/npm*

53 +```

54 +

55 +If you installed things *with* npm, then your best bet is to uninstall

56 +them with npm first, and then install them again once you have a

57 +proper install. This can help find any symlinks that are lying

58 +around:

59 +

60 +```bash

61 +ls -laF /usr/local/{lib/node{,/.npm},bin,share/man} | grep npm

62 +```

63 +

64 +Prior to version 0.3, npm used shim files for executables and node

65 +modules. To track those down, you can do the following:

66 +

67 +```bash

68 +find /usr/local/{lib/node,bin} -exec grep -l npm \{\} \; ;

69 +```

70 +

71 +### See also

72 +

73 +* [npm uninstall](/cli/v8/commands/npm-uninstall)

74 +* [npm prune](/cli/v8/commands/npm-prune)

content/cli/v8/using-npm/scope.md new

+138

@@ -0,0 +1,138 @@

1 +---

2 +title: scope

3 +section: 7

4 +description: Scoped packages

5 +redirect_from:

6 + - /using-npm/scope

7 + - /using-npm/scope.html

8 + - /misc/scope

9 + - /misc/scope.html

10 + - /using-npm/npm-scope

11 +github_repo: npm/cli

12 +github_branch: latest

13 +github_path: docs/content/using-npm/scope.md

14 +---

15 +

16 +### Description

17 +

18 +All npm packages have a name. Some package names also have a scope. A scope

19 +follows the usual rules for package names (URL-safe characters, no leading dots

20 +or underscores). When used in package names, scopes are preceded by an `@` symbol

21 +and followed by a slash, e.g.

22 +

23 +```bash

24 +@somescope/somepackagename

25 +```

26 +

27 +Scopes are a way of grouping related packages together, and also affect a few

28 +things about the way npm treats the package.

29 +

30 +Each npm user/organization has their own scope, and only you can add packages

31 +in your scope. This means you don't have to worry about someone taking your

32 +package name ahead of you. Thus it is also a good way to signal official packages

33 +for organizations.

34 +

35 +Scoped packages can be published and installed as of `npm@2` and are supported

36 +by the primary npm registry. Unscoped packages can depend on scoped packages and

37 +vice versa. The npm client is backwards-compatible with unscoped registries,

38 +so it can be used to work with scoped and unscoped registries at the same time.

39 +

40 +### Installing scoped packages

41 +

42 +Scoped packages are installed to a sub-folder of the regular installation

43 +folder, e.g. if your other packages are installed in `node_modules/packagename`,

44 +scoped modules will be installed in `node_modules/@myorg/packagename`. The scope

45 +folder (`@myorg`) is simply the name of the scope preceded by an `@` symbol, and can

46 +contain any number of scoped packages.

47 +

48 +A scoped package is installed by referencing it by name, preceded by an

49 +`@` symbol, in `npm install`:

50 +

51 +```bash

52 +npm install @myorg/mypackage

53 +```

54 +

55 +Or in `package.json`:

56 +

57 +```json

58 +"dependencies": {

59 + "@myorg/mypackage": "^1.3.0"

60 +}

61 +```

62 +

63 +Note that if the `@` symbol is omitted, in either case, npm will instead attempt to

64 +install from GitHub; see [`npm install`](/cli/v8/commands/npm-install).

65 +

66 +### Requiring scoped packages

67 +

68 +Because scoped packages are installed into a scope folder, you have to

69 +include the name of the scope when requiring them in your code, e.g.

70 +

71 +```javascript

72 +require('@myorg/mypackage')

73 +```

74 +

75 +There is nothing special about the way Node treats scope folders. This

76 +simply requires the `mypackage` module in the folder named `@myorg`.

77 +

78 +### Publishing scoped packages

79 +

80 +Scoped packages can be published from the CLI as of `npm@2` and can be

81 +published to any registry that supports them, including the primary npm

82 +registry.

83 +

84 +(As of 2015-04-19, and with npm 2.0 or better, the primary npm registry

85 +**does** support scoped packages.)

86 +

87 +If you wish, you may associate a scope with a registry; see below.

88 +

89 +#### Publishing public scoped packages to the primary npm registry

90 +

91 +To publish a public scoped package, you must specify `--access public` with

92 +the initial publication. This will publish the package and set access

93 +to `public` as if you had run `npm access public` after publishing.

94 +

95 +#### Publishing private scoped packages to the npm registry

96 +

97 +To publish a private scoped package to the npm registry, you must have

98 +an [npm Private Modules](https://docs.npmjs.com/private-modules/intro)

99 +account.

100 +

101 +You can then publish the module with `npm publish` or `npm publish

102 +--access restricted`, and it will be present in the npm registry, with

103 +restricted access. You can then change the access permissions, if

104 +desired, with `npm access` or on the npmjs.com website.

105 +

106 +### Associating a scope with a registry

107 +

108 +Scopes can be associated with a separate registry. This allows you to

109 +seamlessly use a mix of packages from the primary npm registry and one or more

110 +private registries, such as [GitHub Packages](https://github.com/features/packages) or the open source [Verdaccio](https://verdaccio.org)

111 +project.

112 +

113 +You can associate a scope with a registry at login, e.g.

114 +

115 +```bash

116 +npm login --registry=http://reg.example.com --scope=@myco

117 +```

118 +

119 +Scopes have a many-to-one relationship with registries: one registry can

120 +host multiple scopes, but a scope only ever points to one registry.

121 +

122 +You can also associate a scope with a registry using `npm config`:

123 +

124 +```bash

125 +npm config set @myco:registry http://reg.example.com

126 +```

127 +

128 +Once a scope is associated with a registry, any `npm install` for a package

129 +with that scope will request packages from that registry instead. Any

130 +`npm publish` for a package name that contains the scope will be published to

131 +that registry instead.

132 +

133 +### See also

134 +

135 +* [npm install](/cli/v8/commands/npm-install)

136 +* [npm publish](/cli/v8/commands/npm-publish)

137 +* [npm access](/cli/v8/commands/npm-access)

138 +* [npm registry](/cli/v8/using-npm/registry)

content/cli/v8/using-npm/scripts.md new

+361

@@ -0,0 +1,361 @@

1 +---

2 +title: scripts

3 +section: 7

4 +description: How npm handles the "scripts" field

5 +redirect_from:

6 + - /using-npm/scripts

7 + - /using-npm/scripts.html

8 + - /misc/scripts

9 + - /misc/scripts.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/scripts.md

13 +---

14 +

15 +### Description

16 +

17 +The `"scripts"` property of your `package.json` file supports a number

18 +of built-in scripts and their preset life cycle events as well as

19 +arbitrary scripts. These all can be executed by running

20 +`npm run-script <stage>` or `npm run <stage>` for short. *Pre* and *post*

21 +commands with matching names will be run for those as well (e.g. `premyscript`,

22 +`myscript`, `postmyscript`). Scripts from dependencies can be run with

23 +`npm explore <pkg> -- npm run <stage>`.

24 +

25 +### Pre & Post Scripts

26 +

27 +To create "pre" or "post" scripts for any scripts defined in the

28 +`"scripts"` section of the `package.json`, simply create another script

29 +*with a matching name* and add "pre" or "post" to the beginning of them.

30 +

31 +```json

32 +{

33 + "scripts": {

34 + "precompress": "{{ executes BEFORE the `compress` script }}",

35 + "compress": "{{ run command to compress files }}",

36 + "postcompress": "{{ executes AFTER `compress` script }}"

37 + }

38 +}

39 +```

40 +

41 +In this example `npm run compress` would execute these scripts as

42 +described.

43 +

44 +### Life Cycle Scripts

45 +

46 +There are some special life cycle scripts that happen only in certain

47 +situations. These scripts happen in addition to the `pre<event>`, `post<event>`, and

48 +`<event>` scripts.

49 +

50 +* `prepare`, `prepublish`, `prepublishOnly`, `prepack`, `postpack`

51 +

52 +**prepare** (since `npm@4.0.0`)

53 +* Runs any time before the package is packed, i.e. during `npm publish`

54 + and `npm pack`

55 +* Runs BEFORE the package is packed

56 +* Runs BEFORE the package is published

57 +* Runs on local `npm install` without any arguments

58 +* Run AFTER `prepublish`, but BEFORE `prepublishOnly`

59 +

60 +* NOTE: If a package being installed through git contains a `prepare`

61 + script, its `dependencies` and `devDependencies` will be installed, and

62 + the prepare script will be run, before the package is packaged and

63 + installed.

64 +

65 +* As of `npm@7` these scripts run in the background.

66 + To see the output, run with: `--foreground-scripts`.

67 +

68 +**prepublish** (DEPRECATED)

69 +* Does not run during `npm publish`, but does run during `npm ci`

70 + and `npm install`. See below for more info.

71 +

72 +**prepublishOnly**

73 +* Runs BEFORE the package is prepared and packed, ONLY on `npm publish`.

74 +

75 +**prepack**

76 +* Runs BEFORE a tarball is packed (on "`npm pack`", "`npm publish`", and when installing a git dependencies).

77 +* NOTE: "`npm run pack`" is NOT the same as "`npm pack`". "`npm run pack`" is an arbitrary user defined script name, where as, "`npm pack`" is a CLI defined command.

78 +

79 +**postpack**

80 +* Runs AFTER the tarball has been generated but before it is moved to its final destination (if at all, publish does not save the tarball locally)

81 +

82 +#### Prepare and Prepublish

83 +

84 +**Deprecation Note: prepublish**

85 +

86 +Since `npm@1.1.71`, the npm CLI has run the `prepublish` script for both `npm publish` and `npm install`, because it's a convenient way to prepare a package for use (some common use cases are described in the section below). It has also turned out to be, in practice, [very confusing](https://github.com/npm/npm/issues/10074). As of `npm@4.0.0`, a new event has been introduced, `prepare`, that preserves this existing behavior. A _new_ event, `prepublishOnly` has been added as a transitional strategy to allow users to avoid the confusing behavior of existing npm versions and only run on `npm publish` (for instance, running the tests one last time to ensure they're in good shape).

87 +

88 +See <https://github.com/npm/npm/issues/10074> for a much lengthier justification, with further reading, for this change.

89 +

90 +**Use Cases**

91 +

92 +If you need to perform operations on your package before it is used, in a way that is not dependent on the operating system or architecture of the target system, use a `prepublish` script. This includes tasks such as:

93 +

94 +* Compiling CoffeeScript source code into JavaScript.

95 +* Creating minified versions of JavaScript source code.

96 +* Fetching remote resources that your package will use.

97 +

98 +The advantage of doing these things at `prepublish` time is that they can be done once, in a single place, thus reducing complexity and variability. Additionally, this means that:

99 +

100 +* You can depend on `coffee-script` as a `devDependency`, and thus

101 + your users don't need to have it installed.

102 +* You don't need to include minifiers in your package, reducing

103 + the size for your users.

104 +* You don't need to rely on your users having `curl` or `wget` or

105 + other system tools on the target machines.

106 +

107 +### Life Cycle Operation Order

108 +

109 +#### [`npm cache add`](/cli/v8/commands/npm-cache)

110 +

111 +* `prepare`

112 +

113 +#### [`npm ci`](/cli/v8/commands/npm-ci)

114 +

115 +* `preinstall`

116 +* `install`

117 +* `postinstall`

118 +* `prepublish`

119 +* `preprepare`

120 +* `prepare`

121 +* `postprepare`

122 +

123 + These all run after the actual installation of modules into

124 + `node_modules`, in order, with no internal actions happening in between

125 +

126 +#### [`npm diff`](/cli/v8/commands/npm-diff)

127 +

128 +* `prepare`

129 +

130 +#### [`npm install`](/cli/v8/commands/npm-install)

131 +

132 +These also run when you run `npm install -g <pkg-name>`

133 +

134 +* `preinstall`

135 +* `install`

136 +* `postinstall`

137 +* `prepublish`

138 +* `preprepare`

139 +* `prepare`

140 +* `postprepare`

141 +

142 +If there is a `binding.gyp` file in the root of your package and you

143 +haven't defined your own `install` or `preinstall` scripts, npm will

144 +default the `install` command to compile using node-gyp via `node-gyp

145 +rebuild`

146 +

147 +These are run from the scripts of `<pkg-name>`

148 +

149 +#### [`npm pack`](/cli/v8/commands/npm-pack)

150 +

151 +* `prepack`

152 +* `prepare`

153 +* `postpack`

154 +

155 +#### [`npm publish`](/cli/v8/commands/npm-publish)

156 +

157 +* `prepublishOnly`

158 +* `prepack`

159 +* `prepare`

160 +* `postpack`

161 +* `publish`

162 +* `postpublish`

163 +

164 +`prepare` will not run during `--dry-run`

165 +

166 +#### [`npm rebuild`](/cli/v8/commands/npm-rebuild)

167 +

168 +* `preinstall`

169 +* `install`

170 +* `postinstall`

171 +* `prepare`

172 +

173 +`prepare` is only run if the current directory is a symlink (e.g. with

174 +linked packages)

175 +

176 +#### [`npm restart`](/cli/v8/commands/npm-restart)

177 +

178 +If there is a `restart` script defined, these events are run, otherwise

179 +`stop` and `start` are both run if present, including their `pre` and

180 +`post` iterations)

181 +

182 +* `prerestart`

183 +* `restart`

184 +* `postrestart`

185 +

186 +#### [`npm run <user defined>`](/cli/v8/commands/npm-run-script)

187 +

188 +* `pre<user-defined>`

189 +* `<user-defined>`

190 +* `post<user-defined>`

191 +

192 +#### [`npm start`](/cli/v8/commands/npm-start)

193 +

194 +* `prestart`

195 +* `start`

196 +* `poststart`

197 +

198 +If there is a `server.js` file in the root of your package, then npm

199 +will default the `start` command to `node server.js`. `prestart` and

200 +`poststart` will still run in this case.

201 +

202 +#### [`npm stop`](/cli/v8/commands/npm-stop)

203 +

204 +* `prestop`

205 +* `stop`

206 +* `poststop`

207 +

208 +#### [`npm test`](/cli/v8/commands/npm-test)

209 +

210 +* `pretest`

211 +* `test`

212 +* `posttest`

213 +

214 +#### A Note on a lack of [`npm uninstall`](/cli/v8/commands/npm-uninstall) scripts

215 +

216 +While npm v6 had `uninstall` lifecycle scripts, npm v7 does not. Removal of a package can happen for a wide variety of reasons, and there's no clear way to currently give the script enough context to be useful.

217 +

218 +Reasons for a package removal include:

219 +

220 +* a user directly uninstalled this package

221 +* a user uninstalled a dependant package and so this dependency is being uninstalled

222 +* a user uninstalled a dependant package but another package also depends on this version

223 +* this version has been merged as a duplicate with another version

224 +* etc.

225 +

226 +Due to the lack of necessary context, `uninstall` lifecycle scripts are not implemented and will not function.

227 +

228 +### User

229 +

230 +When npm is run as root, scripts are always run with the effective uid

231 +and gid of the working directory owner.

232 +

233 +### Environment

234 +

235 +Package scripts run in an environment where many pieces of information

236 +are made available regarding the setup of npm and the current state of

237 +the process.

238 +

239 +#### path

240 +

241 +If you depend on modules that define executable scripts, like test

242 +suites, then those executables will be added to the `PATH` for

243 +executing the scripts. So, if your package.json has this:

244 +

245 +```json

246 +{

247 + "name" : "foo",

248 + "dependencies" : {

249 + "bar" : "0.1.x"

250 + },

251 + "scripts": {

252 + "start" : "bar ./test"

253 + }

254 +}

255 +```

256 +

257 +then you could run `npm start` to execute the `bar` script, which is

258 +exported into the `node_modules/.bin` directory on `npm install`.

259 +

260 +#### package.json vars

261 +

262 +The package.json fields are tacked onto the `npm_package_` prefix. So,

263 +for instance, if you had `{"name":"foo", "version":"1.2.5"}` in your

264 +package.json file, then your package scripts would have the

265 +`npm_package_name` environment variable set to "foo", and the

266 +`npm_package_version` set to "1.2.5". You can access these variables

267 +in your code with `process.env.npm_package_name` and

268 +`process.env.npm_package_version`, and so on for other fields.

269 +

270 +See [`package-json.md`](/cli/v8/configuring-npm/package-json) for more on package configs.

271 +

272 +#### current lifecycle event

273 +

274 +Lastly, the `npm_lifecycle_event` environment variable is set to

275 +whichever stage of the cycle is being executed. So, you could have a

276 +single script used for different parts of the process which switches

277 +based on what's currently happening.

278 +

279 +Objects are flattened following this format, so if you had

280 +`{"scripts":{"install":"foo.js"}}` in your package.json, then you'd

281 +see this in the script:

282 +

283 +```bash

284 +process.env.npm_package_scripts_install === "foo.js"

285 +```

286 +

287 +### Examples

288 +

289 +For example, if your package.json contains this:

290 +

291 +```json

292 +{

293 + "scripts" : {

294 + "install" : "scripts/install.js",

295 + "postinstall" : "scripts/install.js",

296 + "uninstall" : "scripts/uninstall.js"

297 + }

298 +}

299 +```

300 +

301 +then `scripts/install.js` will be called for the install

302 +and post-install stages of the lifecycle, and `scripts/uninstall.js`

303 +will be called when the package is uninstalled. Since

304 +`scripts/install.js` is running for two different phases, it would

305 +be wise in this case to look at the `npm_lifecycle_event` environment

306 +variable.

307 +

308 +If you want to run a make command, you can do so. This works just

309 +fine:

310 +

311 +```json

312 +{

313 + "scripts" : {

314 + "preinstall" : "./configure",

315 + "install" : "make && make install",

316 + "test" : "make test"

317 + }

318 +}

319 +```

320 +

321 +### Exiting

322 +

323 +Scripts are run by passing the line as a script argument to `sh`.

324 +

325 +If the script exits with a code other than 0, then this will abort the

326 +process.

327 +

328 +Note that these script files don't have to be Node.js or even

329 +JavaScript programs. They just have to be some kind of executable

330 +file.

331 +

332 +### Best Practices

333 +

334 +* Don't exit with a non-zero error code unless you *really* mean it.

335 + Except for uninstall scripts, this will cause the npm action to

336 + fail, and potentially be rolled back. If the failure is minor or

337 + only will prevent some optional features, then it's better to just

338 + print a warning and exit successfully.

339 +* Try not to use scripts to do what npm can do for you. Read through

340 + [`package.json`](/cli/v8/configuring-npm/package-json) to see all the things that you can specify and enable

341 + by simply describing your package appropriately. In general, this

342 + will lead to a more robust and consistent state.

343 +* Inspect the env to determine where to put things. For instance, if

344 + the `npm_config_binroot` environment variable is set to `/home/user/bin`, then

345 + don't try to install executables into `/usr/local/bin`. The user

346 + probably set it up that way for a reason.

347 +* Don't prefix your script commands with "sudo". If root permissions

348 + are required for some reason, then it'll fail with that error, and

349 + the user will sudo the npm command in question.

350 +* Don't use `install`. Use a `.gyp` file for compilation, and `prepublish`

351 + for anything else. You should almost never have to explicitly set a

352 + preinstall or install script. If you are doing this, please consider if

353 + there is another option. The only valid use of `install` or `preinstall`

354 + scripts is for compilation which must be done on the target architecture.

355 +

356 +### See Also

357 +

358 +* [npm run-script](/cli/v8/commands/npm-run-script)

359 +* [package.json](/cli/v8/configuring-npm/package-json)

360 +* [npm developers](/cli/v8/using-npm/developers)

361 +* [npm install](/cli/v8/commands/npm-install)

content/cli/v8/using-npm/workspaces.md new

+219

@@ -0,0 +1,219 @@

1 +---

2 +title: workspaces

3 +section: 7

4 +description: Working with workspaces

5 +redirect_from:

6 + - /using-npm/workspaces

7 + - /using-npm/workspaces.html

8 + - /misc/workspaces

9 + - /misc/workspaces.html

10 +github_repo: npm/cli

11 +github_branch: latest

12 +github_path: docs/content/using-npm/workspaces.md

13 +---

14 +

15 +### Description

16 +

17 +**Workspaces** is a generic term that refers to the set of features in the

18 +npm cli that provides support to managing multiple packages from your local

19 +files system from within a singular top-level, root package.

20 +

21 +This set of features makes up for a much more streamlined workflow handling

22 +linked packages from the local file system. Automating the linking process

23 +as part of `npm install` and avoiding manually having to use `npm link` in

24 +order to add references to packages that should be symlinked into the current

25 +`node_modules` folder.

26 +

27 +We also refer to these packages being auto-symlinked during `npm install` as a

28 +single **workspace**, meaning it's a nested package within the current local

29 +file system that is explicitly defined in the [`package.json`](/cli/v8/configuring-npm/package-json#workspaces)

30 +`workspaces` configuration.

31 +

32 +### Defining workspaces

33 +

34 +Workspaces are usually defined via the `workspaces` property of the

35 +[`package.json`](/cli/v8/configuring-npm/package-json#workspaces) file, e.g:

36 +

37 +```json

38 +{

39 + "name": "my-workspaces-powered-project",

40 + "workspaces": [

41 + "workspace-a"

42 + ]

43 +}

44 +```

45 +

46 +Given the above `package.json` example living at a current working

47 +directory `.` that contains a folder named `workspace-a` that itself contains

48 +a `package.json` inside it, defining a Node.js package, e.g:

49 +

50 +```

51 +.

52 ++-- package.json

53 +`-- workspace-a

54 + `-- package.json

55 +```

56 +

57 +The expected result once running `npm install` in this current working

58 +directory `.` is that the folder `workspace-a` will get symlinked to the

59 +`node_modules` folder of the current working dir.

60 +

61 +Below is a post `npm install` example, given that same previous example

62 +structure of files and folders:

63 +

64 +```

65 +.

66 ++-- node_modules

67 +| `-- workspace-a -> ../workspace-a

68 ++-- package-lock.json

69 ++-- package.json

70 +`-- workspace-a

71 + `-- package.json

72 +```

73 +

74 +### Getting started with workspaces

75 +

76 +You may automate the required steps to define a new workspace using

77 +[npm init](/cli/v8/commands/npm-init). For example in a project that already has a

78 +`package.json` defined you can run:

79 +

80 +```

81 +npm init -w ./packages/a

82 +```

83 +

84 +This command will create the missing folders and a new `package.json`

85 +file (if needed) while also making sure to properly configure the

86 +`"workspaces"` property of your root project `package.json`.

87 +

88 +### Adding dependencies to a workspace

89 +

90 +It's possible to directly add/remove/update dependencies of your workspaces

91 +using the [`workspace` config](/cli/v8/using-npm/config#workspace).

92 +

93 +For example, assuming the following structure:

94 +

95 +```

96 +.

97 ++-- package.json

98 +`-- packages

99 + +-- a

100 + | `-- package.json

101 + `-- b

102 + `-- package.json

103 +```

104 +

105 +If you want to add a dependency named `abbrev` from the registry as a

106 +dependency of your workspace **a**, you may use the workspace config to tell

107 +the npm installer that package should be added as a dependency of the provided

108 +workspace:

109 +

110 +```

111 +npm install abbrev -w a

112 +```

113 +

114 +Note: other installing commands such as `uninstall`, `ci`, etc will also

115 +respect the provided `workspace` configuration.

116 +

117 +### Using workspaces

118 +

119 +Given the [specifities of how Node.js handles module resolution](https://nodejs.org/dist/latest-v14.x/docs/api/modules.html#modules_all_together) it's possible to consume any defined workspace

120 +by its declared `package.json` `name`. Continuing from the example defined

121 +above, let's also create a Node.js script that will require the `workspace-a`

122 +example module, e.g:

123 +

124 +```

125 +// ./workspace-a/index.js

126 +module.exports = 'a'

127 +

128 +// ./lib/index.js

129 +const moduleA = require('workspace-a')

130 +console.log(moduleA) // -> a

131 +```

132 +

133 +When running it with:

134 +

135 +`node lib/index.js`

136 +

137 +This demonstrates how the nature of `node_modules` resolution allows for

138 +**workspaces** to enable a portable workflow for requiring each **workspace**

139 +in such a way that is also easy to [publish](/cli/v8/commands/npm-publish) these

140 +nested workspaces to be consumed elsewhere.

141 +

142 +### Running commands in the context of workspaces

143 +

144 +You can use the `workspace` configuration option to run commands in the context

145 +of a configured workspace.

146 +

147 +Following is a quick example on how to use the `npm run` command in the context

148 +of nested workspaces. For a project containing multiple workspaces, e.g:

149 +

150 +```

151 +.

152 ++-- package.json

153 +`-- packages

154 + +-- a

155 + | `-- package.json

156 + `-- b

157 + `-- package.json

158 +```

159 +

160 +By running a command using the `workspace` option, it's possible to run the

161 +given command in the context of that specific workspace. e.g:

162 +

163 +```

164 +npm run test --workspace=a

165 +```

166 +

167 +This will run the `test` script defined within the

168 +`./packages/a/package.json` file.

169 +

170 +Please note that you can also specify this argument multiple times in the

171 +command-line in order to target multiple workspaces, e.g:

172 +

173 +```

174 +npm run test --workspace=a --workspace=b

175 +```

176 +

177 +It's also possible to use the `workspaces` (plural) configuration option to

178 +enable the same behavior but running that command in the context of **all**

179 +configured workspaces. e.g:

180 +

181 +```

182 +npm run test --workspaces

183 +```

184 +

185 +Will run the `test` script in both `./packages/a` and `./packages/b`.

186 +

187 +Commands will be run in each workspace in the order they appear in your `package.json`

188 +

189 +```

190 +{

191 + "workspaces": [ "packages/a", "packages/b" ]

192 +}

193 +```

194 +

195 +Order of run is different with:

196 +

197 +```

198 +{

199 + "workspaces": [ "packages/b", "packages/a" ]

200 +}

201 +```

202 +

203 +### Ignoring missing scripts

204 +

205 +It is not required for all of the workspaces to implement scripts run with the `npm run` command.

206 +

207 +By running the command with the `--if-present` flag, npm will ignore workspaces missing target script.

208 +

209 +```

210 +npm run test --workspaces --if-present

211 +```

212 +

213 +### See also

214 +

215 +* [npm install](/cli/v8/commands/npm-install)

216 +* [npm publish](/cli/v8/commands/npm-publish)

217 +* [npm run-script](/cli/v8/commands/npm-run-script)

218 +* [config](/cli/v8/using-npm/config)

219 +

src/gatsby-theme-doctornpm/nav.yml

+256 -2

@@ -510,10 +510,10 @@

510 - title: Removal

511 url: /cli/v6/using-npm/removal

512 description: Cleaning the slate

513 - - title: Version 7.x (Current release)

513 + - title: Version 7.x (Legacy release)

514 shortName: v7

515 url: /cli/v7

516 - default: true

516 + default: false

517 children:

518 - title: CLI Commands

519 shortName: Commands

@@ -764,3 +764,257 @@

764 - title: Removal

765 url: /cli/v7/using-npm/removal

766 description: Cleaning the slate

767 + - title: Version 8.x (Current release)

768 + shortName: v8

769 + url: /cli/v8

770 + default: true

771 + children:

772 + - title: CLI Commands

773 + shortName: Commands

774 + url: /cli/v8/commands

775 + children:

776 + - title: npm

777 + url: /cli/v8/commands/npm

778 + description: JavaScript package manager

779 + - title: npm access

780 + url: /cli/v8/commands/npm-access

781 + description: Set access level on published packages

782 + - title: npm adduser

783 + url: /cli/v8/commands/npm-adduser

784 + description: Add a registry user account

785 + - title: npm audit

786 + url: /cli/v8/commands/npm-audit

787 + description: Run a security audit

788 + - title: npm bin

789 + url: /cli/v8/commands/npm-bin

790 + description: Display npm bin folder

791 + - title: npm bugs

792 + url: /cli/v8/commands/npm-bugs

793 + description: Bugs for a package in a web browser maybe

794 + - title: npm cache

795 + url: /cli/v8/commands/npm-cache

796 + description: Manipulates packages cache

797 + - title: npm ci

798 + url: /cli/v8/commands/npm-ci

799 + description: Install a project with a clean slate

800 + - title: npm completion

801 + url: /cli/v8/commands/npm-completion

802 + description: Tab completion for npm

803 + - title: npm config

804 + url: /cli/v8/commands/npm-config

805 + description: Manage the npm configuration files

806 + - title: npm dedupe

807 + url: /cli/v8/commands/npm-dedupe

808 + description: Reduce duplication

809 + - title: npm deprecate

810 + url: /cli/v8/commands/npm-deprecate

811 + description: Deprecate a version of a package

812 + - title: npm diff

813 + url: /cli/v8/commands/npm-diff

814 + description: The registry diff command

815 + - title: npm dist-tag

816 + url: /cli/v8/commands/npm-dist-tag

817 + description: Modify package distribution tags

818 + - title: npm docs

819 + url: /cli/v8/commands/npm-docs

820 + description: Docs for a package in a web browser maybe

821 + - title: npm doctor

822 + url: /cli/v8/commands/npm-doctor

823 + description: Check your environments

824 + - title: npm edit

825 + url: /cli/v8/commands/npm-edit

826 + description: Edit an installed package

827 + - title: npm exec

828 + url: /cli/v8/commands/npm-exec

829 + description: Run a command from an npm package

830 + - title: npm explain

831 + url: /cli/v8/commands/npm-explain

832 + description: Explain installed packages

833 + - title: npm explore

834 + url: /cli/v8/commands/npm-explore

835 + description: Browse an installed package

836 + - title: npm find-dupes

837 + url: /cli/v8/commands/npm-find-dupes

838 + description: Find duplication in the package tree

839 + - title: npm fund

840 + url: /cli/v8/commands/npm-fund

841 + description: Retrieve funding information

842 + - title: npm help

843 + url: /cli/v8/commands/npm-help

844 + description: Search npm help documentation

845 + - title: npm help-search

846 + url: /cli/v8/commands/npm-help-search

847 + description: Get help on npm

848 + - title: npm hook

849 + url: /cli/v8/commands/npm-hook

850 + description: Manage registry hooks

851 + - title: npm init

852 + url: /cli/v8/commands/npm-init

853 + description: Create a package.json file

854 + - title: npm install

855 + url: /cli/v8/commands/npm-install

856 + description: Install a package

857 + - title: npm install-ci-test

858 + url: /cli/v8/commands/npm-install-ci-test

859 + description: Install a project with a clean slate and run tests

860 + - title: npm install-test

861 + url: /cli/v8/commands/npm-install-test

862 + description: Install package(s) and run tests

863 + - title: npm link

864 + url: /cli/v8/commands/npm-link

865 + description: Symlink a package folder

866 + - title: npm logout

867 + url: /cli/v8/commands/npm-logout

868 + description: Log out of the registry

869 + - title: npm ls

870 + url: /cli/v8/commands/npm-ls

871 + description: List installed packages

872 + - title: npm org

873 + url: /cli/v8/commands/npm-org

874 + description: Manage orgs

875 + - title: npm outdated

876 + url: /cli/v8/commands/npm-outdated

877 + description: Check for outdated packages

878 + - title: npm owner

879 + url: /cli/v8/commands/npm-owner

880 + description: Manage package owners

881 + - title: npm pack

882 + url: /cli/v8/commands/npm-pack

883 + description: Create a tarball from a package

884 + - title: npm ping

885 + url: /cli/v8/commands/npm-ping

886 + description: Ping npm registry

887 + - title: npm pkg

888 + url: /cli/v8/commands/npm-pkg

889 + description: Manages your package.json

890 + - title: npm prefix

891 + url: /cli/v8/commands/npm-prefix

892 + description: Display prefix

893 + - title: npm profile

894 + url: /cli/v8/commands/npm-profile

895 + description: Change settings on your registry profile

896 + - title: npm prune

897 + url: /cli/v8/commands/npm-prune

898 + description: Remove extraneous packages

899 + - title: npm publish

900 + url: /cli/v8/commands/npm-publish

901 + description: Publish a package

902 + - title: npm rebuild

903 + url: /cli/v8/commands/npm-rebuild

904 + description: Rebuild a package

905 + - title: npm repo

906 + url: /cli/v8/commands/npm-repo

907 + description: Open package repository page in the browser

908 + - title: npm restart

909 + url: /cli/v8/commands/npm-restart

910 + description: Restart a package

911 + - title: npm root

912 + url: /cli/v8/commands/npm-root

913 + description: Display npm root

914 + - title: npm run-script

915 + url: /cli/v8/commands/npm-run-script

916 + description: Run arbitrary package scripts

917 + - title: npm search

918 + url: /cli/v8/commands/npm-search

919 + description: Search for packages

920 + - title: npm set-script

921 + url: /cli/v8/commands/npm-set-script

922 + description: Set tasks in the scripts section of package.json

923 + - title: npm shrinkwrap

924 + url: /cli/v8/commands/npm-shrinkwrap

925 + description: Lock down dependency versions for publication

926 + - title: npm star

927 + url: /cli/v8/commands/npm-star

928 + description: Mark your favorite packages

929 + - title: npm stars

930 + url: /cli/v8/commands/npm-stars

931 + description: View packages marked as favorites

932 + - title: npm start

933 + url: /cli/v8/commands/npm-start

934 + description: Start a package

935 + - title: npm stop

936 + url: /cli/v8/commands/npm-stop

937 + description: Stop a package

938 + - title: npm team

939 + url: /cli/v8/commands/npm-team

940 + description: Manage organization teams and team memberships

941 + - title: npm test

942 + url: /cli/v8/commands/npm-test

943 + description: Test a package

944 + - title: npm token

945 + url: /cli/v8/commands/npm-token

946 + description: Manage your authentication tokens

947 + - title: npm uninstall

948 + url: /cli/v8/commands/npm-uninstall

949 + description: Remove a package

950 + - title: npm unpublish

951 + url: /cli/v8/commands/npm-unpublish

952 + description: Remove a package from the registry

953 + - title: npm unstar

954 + url: /cli/v8/commands/npm-unstar

955 + description: Remove an item from your favorite packages

956 + - title: npm update

957 + url: /cli/v8/commands/npm-update

958 + description: Update a package

959 + - title: npm version

960 + url: /cli/v8/commands/npm-version

961 + description: Bump a package version

962 + - title: npm view

963 + url: /cli/v8/commands/npm-view

964 + description: View registry info

965 + - title: npm whoami

966 + url: /cli/v8/commands/npm-whoami

967 + description: Display npm username

968 + - title: npx

969 + url: /cli/v8/commands/npx

970 + description: Run a command from an npm package

971 + - title: Configuring npm

972 + shortName: Configuring

973 + url: /cli/v8/configuring-npm

974 + children:

975 + - title: Install

976 + url: /cli/v8/configuring-npm/install

977 + description: Download and install node and npm

978 + - title: Folders

979 + url: /cli/v8/configuring-npm/folders

980 + description: Folder structures used by npm

981 + - title: .npmrc

982 + url: /cli/v8/configuring-npm/npmrc

983 + description: The npm config files

984 + - title: npm-shrinkwrap.json

985 + url: /cli/v8/configuring-npm/npm-shrinkwrap-json

986 + description: A publishable lockfile

987 + - title: package.json

988 + url: /cli/v8/configuring-npm/package-json

989 + description: Specifics of npm's package.json handling

990 + - title: package-lock.json

991 + url: /cli/v8/configuring-npm/package-lock-json

992 + description: A manifestation of the manifest

993 + - title: Using npm

994 + shortName: Using

995 + url: /cli/v8/using-npm

996 + children:

997 + - title: Registry

998 + url: /cli/v8/using-npm/registry

999 + description: The JavaScript Package Registry

1000 + - title: Config

1001 + url: /cli/v8/using-npm/config

1002 + description: About npm configuration

1003 + - title: Scope

1004 + url: /cli/v8/using-npm/scope

1005 + description: Scoped packages

1006 + - title: Scripts

1007 + url: /cli/v8/using-npm/scripts

1008 + description: How npm handles the "scripts" field

1009 + - title: Workspaces

1010 + url: /cli/v8/using-npm/workspaces

1011 + description: Working with workspaces

1012 + - title: Organizations

1013 + url: /cli/v8/using-npm/orgs

1014 + description: Working with teams & organizations

1015 + - title: Developers

1016 + url: /cli/v8/using-npm/developers

1017 + description: Developer guide

1018 + - title: Removal

1019 + url: /cli/v8/using-npm/removal

1020 + description: Cleaning the slate