NPM Package Specifier Parser

What you write after a package name is not only a version number. npm accepts a range, a dist-tag, a git repository, a tarball URL, a local path, a GitHub shorthand and an alias — and each form resolves differently at install time. The page identifies which one you have in hand and explains what it implies.

The most useful distinction is between an exact version, a range and a dist-tag. An exact version pins; a range lets npm choose at install time; a dist-tag is a published name pointing at a version that can change without notice. There is also a real ambiguity: npm tries to read the text as a range and, failing that, as a dist-tag — so a typo in a range can turn into a search for a tag that does not exist.

The forms that skip the registry deserve attention. A git repository with no ref after the hash installs the default branch, which means the same install at two moments can bring different code. A path with file: creates a symlink rather than copying, so a change in the source folder shows up immediately — excellent in development, bad in a container image.