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 to selecting all of
113 the nested workspaces)
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: false
127 • Type: Boolean
129 Enable running a command in the context of all the configured
132 workspaces.
133 This value is not exported to the environment for child processes.
135 <!-- automatically generated, do not edit manually --> <!-- see
136 lib/utils/config/definitions.js -->
137 <!-- AUTOGENERATED CONFIG DESCRIPTIONS END -->
139 Description
142 Run this in a package directory to bump the version and write the new
143 data back to package.json, package-lock.json, and, if present,
144 npm-shrinkwrap.json.
145 The newversion argument should be a valid semver string, a valid second
147 argument to semver.inc https://github.com/npm/node-semver#functions
148 (one of patch, minor, major, prepatch, preminor, premajor, prerelease),
149 or from-git. In the second case, the existing version will be incre‐
150 mented by 1 in the specified field. from-git will try to read the lat‐
151 est git tag, and use that as the new npm version.
152 If run in a git repo, it will also create a version commit and tag.
154 This behavior is controlled by git-tag-version (see below), and can be
155 disabled on the command line by running npm --no-git-tag-version ver‐
156 sion. It will fail if the working directory is not clean, unless the
157 -f or --force flag is set.
158 If supplied with -m or --message config option, npm will use it as a
160 commit message when creating a version commit. If the message config
161 contains %s then that will be replaced with the resulting version num‐
162 ber. For example:
163 npm version patch -m "Upgrade to %s for reasons"
165 If the sign-git-tag config is set, then the tag will be signed using
167 the -s flag to git. Note that you must have a default GPG key set up
168 in your git config for this to work properly. For example:
169 $ npm config set sign-git-tag true
171 $ npm version patch
172 You need a passphrase to unlock the secret key for
174 user: "isaacs (http://blog.izs.me/) <i@izs.me>"
175 2048-bit RSA key, ID 6C481CF6, created 2010-08-31
176 Enter passphrase:
178 If preversion, version, or postversion are in the scripts property of
180 the package.json, they will be executed as part of running npm version.
181 The exact order of execution is as follows:
183 1. Check to make sure the git working directory is clean before we get
185 started. Your scripts may add files to the commit in future steps.
186 This step is skipped if the --force flag is set.
187 2. Run the preversion script. These scripts have access to the old ver‐
189 sion in package.json. A typical use would be running your full test
190 suite before deploying. Any files you want added to the commit
191 should be explicitly added using git add.
192 3. Bump version in package.json as requested (patch, minor, major,
194 etc).
195 4. Run the version script. These scripts have access to the new version
197 in package.json (so they can incorporate it into file headers in
198 generated files for example). Again, scripts should explicitly add
199 generated files to the commit using git add.
200 5. Commit and tag.
202 6. Run the postversion script. Use it to clean up the file system or
204 automatically push the commit and/or tag.
205 Take the following example:
208 {
210 "scripts": {
211 "preversion": "npm test",
212 "version": "npm run build && git add -A dist",
213 "postversion": "git push && git push --tags && rm -rf build/temp"
214 }
215 }
216 This runs all your tests and proceeds only if they pass. Then runs your
218 build script, and adds everything in the dist directory to the commit.
219 After the commit, it pushes the new commit and tag up to the server,
220 and deletes the build/temp directory.
221 See Also
223 • npm help init
224 • npm help run-script
226 • npm help scripts
228 • npm help package.json
230 • npm help config
232 October 2021 NPM-VERSION(1)