Comprehensive Guide to npm-dedupe, npm-deprecate, and npm-dist-tag Commands

In the previous tutorial we covered npm's ci, completion and config CLI options. The tutorial that you are about to read will cover npm-dedupe, npm-deprecate and npm-dist-tag cli options.

Synopsis

npm dedupe
npm ddp

aliases: find-dupes, ddp

Description

The dedupe option will search the local package tree and then attempt to simplify the overall structure by moving dependencies further up the tree, where they can be shared by multiple dependent packages more effectively.

For instance, consider the dependency graph below:

a
+-- b <-- depends on [email protected]
|   `-- [email protected]
`-- d <-- depends on c@~1.0.9
    `-- [email protected]

Here, npm-dedupe transforms the tree into:

a
+-- b
+-- d
`-- [email protected]

Due to the hierarchical nature of node's module lookup, b and d will both get their dependency met by the single c package at the root level of the tree.

The duplication of the algorithm will walk the tree, moving each of the dependency as far up the tree as possible, even when the duplicates are not found. This results in both a flat and a deduplicated tree.

If there is a suitable version already at the target location, then it will be left untouched, but the other duplicates are deleted.

Arguments are ignored. Dedupe will always act on the entire tree.

Modules

It should be noted that this operation will transform the dependency tree, but it will not result in the installation of new modules.

Npm-deprecate

This command deprecates a version of a package.

Synopsis

npm deprecate <pkg>[@<version>] <message>

Description

This CLI command updates the npm registry entry for a package, providing a deprecation warning to all who attempt to install it.

It will work of version ranges as well as specific versions, hence you can do this:

npm deprecate my-thing@"< 0.2.3" "critical bug fixed in v0.2.3"

It should be noted that you have to be the owner of a package to deprecate it. If you want to un-deprecate a package, you will have to specify an empty string ("") for the message argument.

Npm-dis-tag

This command is used to modify the package distribution tags.

Synopsis

 npm dist-tag add <pkg>@<version> [<tag>]
npm dist-tag rm <pkg> <tag>
npm dist-tag ls [<pkg>]

aliases: dist-tags

Description

This command either adds, removes or enumerates distribution tags on a package:

• add: This will tag the specified version of the package with the specified tag, or the --tag config if it is not specified. If the tag you're adding is the latest and you set up two-factor authentication on auth-and-writes then you will need to include an otp on the command line using --otp.
• rm: Clears a tag that is no longer in use from the package.
• ls: Shows all of the dist-tags for a package, it defaults to the package in the current prefix.

You can use a tag when installing packages as a reference to a version rather than using a specific version number:

npm install <name>@<tag>

When you are installing dependencies, you can specify a preferred tag version as shown below:

npm install --tag <tag>

This will also apply to npm dedupe.

Publishing of a package will set the latest tag to the published version unless the ?tag is used. For instance, npm publish -tag=beta.

Npm install <pkg> (without including any @<version> or @<tag> specifier) will install the latest tag by default.

PURPOSE

You can use tags to provide an alias instead of version numbers.

For instance, a project could have multiple streams of development and use a different tag for each of the streams, e.g., stable, beta, dev, canary.

By default, the latest tag will be used by npm to identify the current version of a package, and npm install <pkg> (without any @<version> or @<tag> specifier) will install the latest tag. Typically, projects will only use the latest tag for stable release versions, and use other tags for any unstable version such as prereleases.

The next tag will be used by some projects to identify the upcoming version.

By default, aside the latest tag, no other tag has a special significance to npm itself.

CAVEATS

The npm-dist-tag command used to be known as npm tag, which was only used to create new tags, and thus had a different syntax.

Tags have to share a namespace with version numbers, because they will be specified in the same slot: npm install <pkg>@<version> vs npm install <pkg>@<tag>.

Tags that can be interpreted as valid semver ranges are rejected. For instance, v1.4 cannot be used as a tag, because it will be interpreted by semver as >=1.4.0 <1.5.0.

The easiest way to avoid semver problems with tags is to use tags that do not begin with a number or the letter v.

Previous: Comprehensive Guide to npm-ci, npm-completion, and npm-config Commands.
Next: Comprehensive Guide to npm-docs, npm-doctor, and npm-edit Commands.