SemVer Prerelease and Metadata

SemVer for major, minor, and patch are simple to understand. What about prelease? Here's a quick post for the that, and also about the build metadata.

Prerelease

So, is there a predefined list of prereleases in SemVer? No, it can actually be anything (well, as long as it follows the limitation specified in the BNF). The following are common in the industry for published APIs:

• alpha
• beta
• rc

So how do SemVer implementations, such as npm, know that alpha is before beta, and beta is before rc? As per SevVer 2.0 #11 spec, it's basically checking the ASCII string sort order — and alpha, beta, and rc happen to be in the correct sort order that we want.

Metadata

Sometimes you might see a date string appended to the version number, such as 1.0.0+20190826, and those are called build metadata, and should be ignored in SemVer comparison. Note that they must start with a plus sign, and prereleases must start with a hyphen.

Examples

Here are some examples using the semver package in interactive Node.js, including what happens when the prerelease characters are same but are different in lengths, and mixing capital letters, etc.

User@COMPUTER MINGW64 /c/dev/npm/semvertest
$ npm i --save-dev semver
User@COMPUTER MINGW64 /c/dev/npm/semvertest
$ node
Welcome to Node.js v12.7.0.
Type ".help" for more information.
> const semver = require('semver');
undefined
> semver.gt('1.0.0-aaa', '1.0.0-aaaa') // length difference
false
> semver.gt('1.0.0-abaa', '1.0.0-aaaa') // letter difference
true
> semver.gt('1.0.0-A', '1.0.0-a') // ASCII(A) = 65, ASCII(a) = 97
false
> semver.gt('1.0.0-aaa.1', '1.0.0-aaaa.5') // length difference variation
false
> semver.gt('1.0.0-a.256', '1.0.0-a.64') // number in prerelease
true
> semver.gt('1.0.0-a.aaa', '1.0.0-a.bb') // same length as above, but not a number
false
> semver.gt('1.0.0-a.3.b.8', '1.0.0-a.4.b.7') // period separation - not just last number.
false
> semver.eq('1.0.0-aaa+2019-08-26', '1.0.0-aaa+MetaDataHere') // Build metadata are ignored
true
    

npm Install

I've been using npm without giving much thought... Here's a quick post on a couple of options that I wanted to know more about.

npm install [package name] -g (or --global)

• Installs a package in global mode, and not under your local project/package. For Windows, %APPDATA%\npm (e.g., C:\Users\[Username]\AppData\Roaming\npm). Note that this is not where Node.js and npm is installed, that's usually C:\Program Files\nodejs.
• It's mainly for packages with executables, as they will become available from everywhere, since above directory is added to the PATH when you install Node.js (when installed with default options).
• It does not modify package.json of your current project.

An example – let's install Angular CLI:

• npm install @angular/cli -g

After running the command, in the directory mentioned above:

• ng (for bash) and ng.cmd (for Windows) will be added, so you can run ng from any command line window.
• node_modules\@angular will be added.

npm install [package name] --save-dev (or -D)

The package will appear under devDependencies. This means that when you run npm install in production mode, the package will not be installed.

devDependencies are things you need during development and not necessarily in production, such as a unit testing framework.

You might come across npm --save. This has been deprecated, since it's the default option now – npm will add the package under the dependencies section in addition to installing it under node_modules.

How do you run npm install in production mode?

• npm install --production
• If NODE_ENV is set to production, then simply npm install
• To force, regardless of NODE_ENV variable, then npm --only=prod

You can't have a package in both devDependencies and dependencies.

Production mode is more important for server-side apps, i.e., using Node.js. For front-end, if you're just publishing the files after running through a package manager such as WebPack, probably should still be okay to use them as intended, though may need further investigation...

Some other tidbits

• If you run npm install, npm will traverse up to find the root of your project, i.e., the directory with package.json, and install under node_modules from the directory accordingly. If package.json is not found, it will just use the current directory as root.
• In npm lingo, prefix is the root directory of your project, or the global npm directory if -g is used.

Screenshot of Node.js installation step where you specify that npm global directory should be added to the path.

See also: npm docs - npm-folders, npm-install.