1NPM-VERSION(1) NPM-VERSION(1)
2
6 npm-version - Bump a package version
7 Synopsis
9 npm version [<newversion> | major | minor | patch | premajor | preminor | prepatch | prerelease [--preid=<prerelease-id>] | from-git]
10 '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 Configuration
16 <!-- AUTOGENERATED CONFIG DESCRIPTIONS START --> <!-- automatically
17 generated, do not edit manually --> <!-- see lib/utils/config/defini‐
18 tions.js -->
19 allow-same-version
21 • Default: false
22 • Type: Boolean
24 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 commit-hooks
33 • Default: true
34 • Type: Boolean
36 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 git-tag-version
44 • Default: true
45 • Type: Boolean
47 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 json
55 • Default: false
56 • Type: Boolean
58 Whether or not to output JSON data, rather than the normal output.
61 • In npm pkg set it enables parsing set values with JSON.parse() before
63 saving them to your package.json.
64 Not supported by all npm commands. <!-- automatically generated, do
67 not edit manually --> <!-- see lib/utils/config/definitions.js -->
68 preid
71 • Default: ""
72 • Type: String
74 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 sign-git-tag
83 • Default: false
84 • Type: Boolean
86 If set to true, then the npm version command will tag the version using
89 -s to add a signature.
90 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 workspace
97 • Default:
98 • Type: String (can be set multiple times)
100 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 Valid values for the workspace config are either:
107 • Workspace names
109 • Path to a workspace directory
111 • Path to a parent workspace directory (will result in selecting all
113 workspaces within that folder)
114 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 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 workspaces
126 • Default: null
127 • Type: null or Boolean
129 Set to true to run the command in the context of all configured
132 workspaces.
133 Explicitly setting this to false will cause commands like install to
135 ignore workspaces altogether. When not set explicitly:
136 • 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 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 include-workspace-root
150 • Default: false
151 • Type: Boolean
153 Include the workspace root when workspaces are enabled for a command.
156 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 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
164 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 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 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 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 npm version patch -m "Upgrade to %s for reasons"
190 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 $ npm config set sign-git-tag true
196 $ npm version patch
197 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 Enter passphrase:
203 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 The exact order of execution is as follows:
208 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 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 3. Bump version in package.json as requested (patch, minor, major,
219 etc).
220 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 5. Commit and tag.
227 6. Run the postversion script. Use it to clean up the file system or
229 automatically push the commit and/or tag.
230 Take the following example:
233 {
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 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 See Also
248 • npm help init
249 • npm help run-script
251 • npm help scripts
253 • npm help package.json
255 • npm help config
257 January 2022 NPM-VERSION(1)