1NPM-VERSION(1) NPM-VERSION(1)
2
3
4
6 npm-version - Bump a package version
7
8 Synopsis
9 npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
10
11 'npm [-v | --version]' to print npm version
12 'npm view <pkg> version' to view a package's published version
13 'npm ls' to inspect current package/dependency versions
14
15 Configuration
16 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> <!-- automatically
17 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
18 tions.js -->
19
20 allow-same-version
21 • Default: false
22
23 • Type: Boolean
24
25
26 Prevents throwing an error when npm version is used to set the new ver‐
27 sion to the same value as the current version. <!-- automatically gen‐
28 erated, do not edit manually --> <!-- see lib/utils/config/defini‐
29 tions.js -->
30
31
32 commit-hooks
33 • Default: true
34
35 • Type: Boolean
36
37
38 Run git commit hooks when using the npm version command. <!-- automat‐
39 ically generated, do not edit manually --> <!-- see lib/utils/con‐
40 fig/definitions.js -->
41
42
43 git-tag-version
44 • Default: true
45
46 • Type: Boolean
47
48
49 Tag the commit when using the npm version command. <!-- automatically
50 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
51 tions.js -->
52
53
54 json
55 • Default: false
56
57 • Type: Boolean
58
59
60 Whether or not to output JSON data, rather than the normal output.
61
62 • In npm pkg set it enables parsing set values with JSON.parse() before
63 saving them to your package.json.
64
65
66 Not supported by all npm commands. <!-- automatically generated, do
67 not edit manually --> <!-- see lib/utils/config/definitions.js -->
68
69
70 preid
71 • Default: ""
72
73 • Type: String
74
75
76 The "prerelease identifier" to use as a prefix for the "prerelease"
77 part of a semver. Like the rc in 1.2.0-rc.8. <!-- automatically gener‐
78 ated, do not edit manually --> <!-- see lib/utils/config/definitions.js
79 -->
80
81
82 sign-git-tag
83 • Default: false
84
85 • Type: Boolean
86
87
88 If set to true, then the npm version command will tag the version using
89 -s to add a signature.
90
91 Note that git requires you to have set up GPG keys in your git configs
92 for this to work properly. <!-- automatically generated, do not edit
93 manually --> <!-- see lib/utils/config/definitions.js -->
94
95
96 workspace
97 • Default:
98
99 • Type: String (can be set multiple times)
100
101
102 Enable running a command in the context of the configured workspaces of
103 the current project while filtering by running only the workspaces de‐
104 fined by this configuration option.
105
106 Valid values for the workspace config are either:
107
108 • Workspace names
109
110 • Path to a workspace directory
111
112 • Path to a parent workspace directory (will result in selecting all
113 workspaces within that folder)
114
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
118 as a brand new workspace within the project.
119
120 This value is not exported to the environment for child processes.
121 <!-- automatically generated, do not edit manually --> <!-- see
122 lib/utils/config/definitions.js -->
123
124
125 workspaces
126 • Default: null
127
128 • Type: null or Boolean
129
130
131 Set to true to run the command in the context of all configured
132 workspaces.
133
134 Explicitly setting this to false will cause commands like install to
135 ignore workspaces altogether. When not set explicitly:
136
137 • Commands that operate on the node_modules tree (install, update,
138 etc.) will link workspaces into the node_modules folder. - Commands
139 that do other things (test, exec, publish, etc.) will operate on the
140 root project, unless one or more workspaces are specified in the
141 workspace config.
142
143
144 This value is not exported to the environment for child processes.
145 <!-- automatically generated, do not edit manually --> <!-- see
146 lib/utils/config/definitions.js -->
147
148
149 include-workspace-root
150 • Default: false
151
152 • Type: Boolean
153
154
155 Include the workspace root when workspaces are enabled for a command.
156
157 When false, specifying individual workspaces via the workspace config,
158 or all workspaces via the workspaces flag, will cause npm to operate
159 only on the specified workspaces, and not on the root project. <!--
160 automatically generated, do not edit manually --> <!-- see
161 lib/utils/config/definitions.js -->
162
163 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
164
165
166 Description
167 Run this in a package directory to bump the version and write the new
168 data 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
173 (one of patch, minor, major, prepatch, preminor, premajor, prerelease),
174 or from-git. In the second case, the existing version will be incre‐
175 mented by 1 in the specified field. from-git will try to read the lat‐
176 est 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.
179 This 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 ver‐
181 sion. It will fail if the working directory is not clean, unless the
182 -f or --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 num‐
187 ber. For example:
188
189 npm version patch -m "Upgrade to %s for reasons"
190
191 If the sign-git-tag config is set, then the tag will be signed using
192 the -s flag to git. Note that you must have a default GPG key set up
193 in your git config for this to work properly. For example:
194
195 $ npm config set sign-git-tag true
196 $ npm version patch
197
198 You need a passphrase to unlock the secret key for
199 user: "isaacs (http://blog.izs.me/) <i@izs.me>"
200 2048-bit RSA key, ID 6C481CF6, created 2010-08-31
201
202 Enter passphrase:
203
204 If preversion, version, or postversion are in the scripts property of
205 the package.json, they will be executed as part of running npm version.
206
207 The exact order of execution is as follows:
208
209 1. Check to make sure the git working directory is clean before we get
210 started. Your scripts may add files to the commit in future steps.
211 This step is skipped if the --force flag is set.
212
213 2. Run the preversion script. These scripts have access to the old ver‐
214 sion in package.json. A typical use would be running your full test
215 suite before deploying. Any files you want added to the commit
216 should be explicitly added using git add.
217
218 3. Bump version in package.json as requested (patch, minor, major,
219 etc).
220
221 4. Run the version script. These scripts have access to the new version
222 in package.json (so they can incorporate it into file headers in
223 generated files for example). Again, scripts should explicitly add
224 generated files to the commit using git add.
225
226 5. Commit and tag.
227
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
232 Take the following example:
233
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 This runs all your tests and proceeds only if they pass. Then runs your
243 build script, and adds everything in the dist directory to the commit.
244 After the commit, it pushes the new commit and tag up to the server,
245 and deletes the build/temp directory.
246
247 See Also
248 • npm help init
249
250 • npm help run-script
251
252 • npm help scripts
253
254 • npm help package.json
255
256 • npm help config
257
258
259
260
261 January 2022 NPM-VERSION(1)