npm version to add alpha postfix

Question

How can i bump the package.json version to contain -alpha using npm versioning.

Running npm version <new version> will bump the version of the package.json file, however i want to add -alpha postfix to the version, but i am unable to as it is not stated in the documentation, but its supported by semver itself.

Actual Result:

> npm version prerelease
> v0.2.1-1

Expected Result:

> v0.2.1-alpha

Answer 1

You cannot set 0.2.1-alpha automatically, but 0.2.1-alpha.0 is possible.

npm supports --preid option to specify the prefix of prereleases. It's available in combination with pre* versions.

Example 1. Make the alpha of next major version:

# 1.2.3 => 2.0.0-alpha.0
npm version premajor --preid alpha

Example 2. Bump alpha to beta:

# 2.0.0-alpha.0 => 2.0.0-beta.0
npm version prerelease --preid beta

Once you create a prerelease, you can increment the number using prerelease argument.

# 2.0.0-beta.0 => 2.0.0-beta.1
npm version prerelease

Answer 2

While -alpha and -beta are common prerelease tags, they are not defined by SemVer. -alpha.1, -alpha.2, -beta.1, etc, are also fairly common. The spec defines the prerelease tag as a series of dot separated alphanumeric or numeric character fields. The SemVer spec uses alpha and beta in some examples, but they are not defined by the spec. NPM has no way of knowing what tag you want to use if you do not tell it. It apparently defaults to numeric prerelease tag, which makes some sense, since SemVer allows that (-1, -2, -3 provides all the necessary semantics).

The NPM documentation sucks and I have fortunately never had to use NPM. See https://docs.npmjs.com/cli/version. Especially:

The newversion argument should be a valid semver string, a valid second argument to semver.inc (one of patch, minor, major, prepatch, preminor, premajor, prerelease), or from-git.

Looking at the provided link (https://github.com/npm/node-semver#functions), they seem to be referring to increasing the specified version field. In the absence of the alpha tag on the version string in the package.json file, it makes a lot of sense that it would append the missing numeric prerelease tag as -1.

I just tested this theory with:

> echo Test > test.txt
> npm init
This utility will walk you through creating a package.json file.
It only covers the most common items, and tries to guess sane defaults.

See `npm help json` for definitive documentation on these fields
and exactly what they do.

Use `npm install <pkg> --save` afterwards to install a package and
save it as a dependency in the package.json file.

Press ^C at any time to quit.
name: (packageTest)
version: (1.0.0) 0.1.0-alpha.0
description: Test package.
entry point: (index.js)
test command:
git repository:
keywords:
author:
license: (ISC)
About to write to D:\TMP\Joseph\packageTest\package.json:

{
  "name": "packageTest",
  "version": "0.1.0-alpha.0",
  "description": "Test package.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}


Is this ok? (yes)

> npm version prerelease
v0.1.0-alpha.1

> cat package.json
{
  "name": "packageTest",
  "version": "0.1.0-alpha.1",
  "description": "Test package.",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1"
  },
  "author": "",
  "license": "ISC"
}

As expected.