Skip to main content

Tagging Packages

Dist-Tags​

A dist-tag (short for distribution tag) in npm is a label that you can apply to specific versions of a package to manage and simplify versioning. Dist-tags are used to direct npm to install a particular version of a package when users specify a tag instead of an exact version number.

Common Use Cases for Dist-Tags​

  1. Latest Release:

    • By default, npm uses the latest tag to reference the most recent stable release version of a package. When users install a package without specifying a version number, npm will install the version associated with the latest tag. For example:

      npm install my-package

  2. Pre-release Versions:

    • You might use other tags like beta, next, or rc (release candidate) to represent pre-release versions. This allows users who want to test new features to easily install these versions:

      npm install my-package@beta

  3. Long-term Support:

    • Tags such as lts can point to versions deemed stable or supported long-term, which users might prefer for production environments.

Managing Dist-Tags​

  • Assigning a Dist-Tag:

    • You can assign a dist-tag during the publishing of a package using the npm publish command with the --tag option:

      npm publish --tag beta

  • Updating a Dist-Tag:

    • You can update a tag to point to a different version using the npm dist-tag add command:

      npm dist-tag add my-package@1.2.3 beta

  • Viewing Dist-Tags:

    • To view the current dist-tags for a package, use:

      npm dist-tag ls my-package

By using dist-tags effectively, package maintainers can offer flexibility in how users install and upgrade packages, making it easier to manage stable releases and pre-releases.

Annotated and Lightweight Tags​

In Git, the -a flag is used to create an "annotated" tag. This means that the tag contains additional metadata, such as the tagger’s name, email, date, and a tagging message. This is different from a "lightweight" tag, which is essentially just a name for a specific commit and doesn't include any additional information.

Annotated Tags:

  • Created with git tag -a <tagname>.
  • Stores additional metadata.
  • Can include a message using -m or by leaving it blank to be prompted for it with an editor.
  • Considered a new object in the Git database.
  • Useful for releases and important milestones because of the extra context they provide.

Lightweight Tags:

  • Created with git tag <tagname> without the -a option.
  • Acts as a simple pointer to a commit, similar to a branch but fixed.
  • Contains no additional metadata or messages.
  • Easier and faster to create, but less informative.

In summary, if you need context or a descriptive message with your tag, use an annotated tag with the -a flag. If you only need a simple pointer to a commit, a lightweight tag is sufficient.

Nx Release :: Tagging​

Scenario: The initial/first release of the package deployment was at version 13.0.0 for the package @your-scope/your-package-name. However, the local Git repository was not tagged with this version. As a result, the Nx Release tool is unable to determine the correct version for subsequent releases.

  1. Tag the Correct Version: Since the version on GitHub Packages is 13.0.0, make sure your local repository reflects this by tagging the same version:

    git checkout main
    git tag -a 13.0.0
    git push origin 13.0.0

    This ensures that your local Git history and GitHub registry are in sync with respect to versioning.

  2. Update Local Files (Optional): Confirm that your local package.json reflects 13.0.0. If it’s different, update it and commit the change:

    {
      "name": "your-package-name",
      "version": "13.0.0",
      ...
    }

    Then commit and push:

    git commit -am "chore: set version to 13.0.0 to match deployed package"
    git push origin main

  3. Run Nx Release: With the correct tag and version in place, re-run the Nx release process. This time, it should correctly identify the current version and compute the next version based on your conventional commits. Make sure to remove the --first-release=true flag if it's still present.

By aligning your local Git tags with the version that was actually deployed, the Nx Release tool should be able to determine the next version correctly based on any subsequent commits you push.