Manage a Published npm Package

When updating a package, by adding a feature, refactoring the code, fixing a bug, etc, you need to update the package version before publishing it in order to reflect those changes.

Bump to a new version

To bump (or increase) a package version according the the semantic versioning (SemVer) rules, you can either manually edit the version field of the package.json file or use the npm version command within the package's directory:

$ npm version [<newversion> | major | minor | patch]

Where:

• <newversion>: the new version number of the package (e.g., 2.2.3).
• major: introduces a breaking change (e.g. 1.0.0 -> 2.0.0).
• minor: introduces a new feature (e.g. 1.0.0 -> 1.1.0).
• patch: introduces a bug fix (e.g. 1.0.0 -> 1.0.1).

For example:

$ npm version minor

Tag a published version

Tags are used to provide an alias instead of version numbers.

By default, the latest tag is used by npm to identify the latest published version of a package, which will be used by the npm install command if no version number or tag is provided.

Typically, projects only use the latest tag for stable release versions, and use other tags such as beta, dev, canary, etc., for unstable versions such as prereleases.

To tag a published package version, you can use the npm dist-tag add command

$ npm dist-tag add <package@version> <tag>

For example:

$ npm dist-tag add hello-world@1.0.0 beta

Deprecate a published version

It sometimes happens that a published package version needs to be deprecated, or in other words, no longer recommended for use.

This typically occurs when the package has security vulnerabilities, unresolved critical bugs, or becomes difficult to maintain due to a complex codebase or limited resources.

Deprecation may also be necessary if the package’s functionality is outdated, a better alternative is available, or its features have been merged into another library.

To deprecate a specific package version, you can use the npm deprecate command:

$ npm deprecate <package>@<version> "<message>"

Where:

• <package> is the name of the package to deprecate.
• <version> is the version of the package to deprecate.
• <message> is a short message providing a deprecation warning to all who attempt to install it.

Note: To deprecate the entire package, you can use this command instead:

$ npm deprecate <package> "<message>"

Unpublish a version

To permanently remove a specific version of a package from the npm registry, making it completely unavailable for users, you can use the npm unpublish command:

$ npm unpublish <package>@<version

This is typically done in rare and critical cases, such as when a package contains sensitive or harmful content, was published by mistake, or violates legal or security policies.

Notes:

• Newly created packages can be unpublish anytime within the first 72 hours after publishing if no other packages in the public npm registry depend on it.
• Older packages can be unpublish anytime if no other packages depend on it, they have less than 300 downloads over the last week, and have a single owner/maintainer.

Summary

Here's a summary of what you've learned in this lesson:

• The npm version command is used to bump the version number of a package.
• The npm dist-tag command is used to tag a package version.
• The npm deprecate command is used to deprecate a package or package version on the public npm registry.
• The npm unpublish command is used to remove a package version from the public npm registry.