Manage Node.js packages

This page describes the following tasks:

Viewing and deleting packages and package versions
Viewing, creating, updating, and deleting tags

Before you begin

If the target repository does not exist, create a new repository.
Verify that you have the required permissions for the repository.
Configure authentication for npm.
(Optional) Configure defaults for gcloud commands.
If you are using the npm credential helper to for authentication, obtain an access token before connecting to a repository with npm.

Obtaining an access token

Access tokens are valid for 60 minutes. Generate an access token shortly before running commands that interact with repositories.

To obtain a token, use one of these options:

Use the npx command to refresh the access token.
1. Ensure that credentials for connecting to the public npm registry are in your user npm configuration file, ~/.npmrc.
2. Run the following command in your Node.js project directory.
```
npx google-artifactregistry-auth
```

Add a script to the package.json file in your project.

"scripts": {
 "artifactregistry-login": "npx google-artifactregistry-auth"
}

Run the script in your Node.js project directory.

npm run artifactregistry-login

Artifact Registry reads Artifact Registry repository settings in your project .npmrc file and uses them to add token credentials to your user .npmrc file. Storing the token in your user .npmrc file isolates your credentials from your source code and your source control system.

Adding packages

You can only publish a specific version of a package once. This is an npm restriction to ensure that the contents of a published package version are always the same. As a result, you cannot:

Overwrite a package version by publishing it again to the repository
Remove a package or its version from the repository, and then publish a package with the same name and version number

If you don't specify a tag when you publish a package, npm adds the latest tag. To simplify installation of your packages at a specific development stage, consider publishing your packages with a tag, such as beta or dev.

To add a package:

Ensure that the package name in package.json includes the scope configured for your repository. The following example shows a package with the scope dev-repo.
```
"name": "@dev-repo/my-package"
```
If you are using the credential helper to authenticate with an access token, obtain a new token.
Add packages to the repository. You can use an npm or yarn command.

To tag the package, include the --tag flag and replace TAG with the tag you want to use. If you do not include the --tag flag, npm automatically sets the tag to latest.
```
npm publish --tag=TAG
```
```
yarn publish --tag TAG
```

Viewing packages and versions

To get package information with npm or yarn:

If you are using the credential helper to authenticate with an access token, obtain a new token.
Run the appropriate command:
```
npm view
```
```
yarn info
```

To view packages and package versions using the Google Cloud console or gcloud:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
Click a package to view versions of the package.

gcloud

To list packages in a repository, run the following command:

gcloud artifacts packages list [--repository=REPOSITORY] [--location=LOCATION]

Where

REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

To view versions of a package, run the following command:

gcloud artifacts versions list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Where

PACKAGE is the ID of the package or fully qualified identifier for the package.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

Listing files

You can list files in a repository, files in all versions of a specified container package, or files in a specific version of an package.

For all the following commands, you can set a maximum number of files to return by adding the --limit flag to the command.

To list all files in the default project, repository, and location when the default values are configured:

gcloud artifacts files list

To list files in a specified project, repository, and location, run the command:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION

To list files for all versions of a specific package:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE

To list files for a specific package version:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --version=VERSION

To list files for a specific tag:

gcloud artifacts files list
    --project=PROJECT \
    --repository=REPOSITORY \
    --location=LOCATION \
    --package=PACKAGE \
    --tag=TAG

Replace the following values:

LOCATION is the regional or multi-regional location of the repository.
PROJECT is your Google Cloud project ID. If your project ID contains a colon (:), see Domain-scoped projects.
REPOSITORY is the name of the repository where the image is stored.
PACKAGE is the name of the package.
VERSION is the version of the package.
TAG is the tag associated with the package.

Examples

Consider the following package information:

Project: my-project
Repository: my-repo
Repository location: us-central1
Package: my-app

The following command lists all files in the repository my-repo in the location us-central1 within the default project:

gcloud artifacts files list
    --location=us-central1 \
    --repository=my-repo

The following command lists files in version 1.0 of the package.

gcloud artifacts files list
    --project=my-project \
    --location=us-central1 \
    --repository=my-repo \
    --package=my-app \
    --version=1.0

The following command lists files in the version of the package with the tag 1.0-dev

gcloud artifacts files list
    --project=my-project \
    --location=us-central1 \
    --repository=my-repo \
    --package=my-app \
    --tag=1.0-dev

Tagging packages

You can view, add, update, and delete tags. Tags can help you manage semantic versions of your packages and streamline installation of packages at a specific stage of development.

For example, you can tag the current release candidate build with rc. Your team can then install the correct version based on the tag instead of a version specifier, and unpublishing unused pre-release versions won't break your dependencies on the release candidate package.

Viewing tags

To view tags for a package:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
Click the package to view versions and the associated tags.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
Type new tags into the field and then click SAVE.

gcloud

Run the command:

gcloud artifacts tags list --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION]

Where

PACKAGE is the name of the package in the repository.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.

For example, to view tags for the package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags list --package=my-pkg --repository=my-repo

Creating tags

You can create a tag for a specific version of a package.

To tag an existing image in a repository:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
Click the package to view versions of the package.
Select the package version to tag.
In the row of the selected version, click More actions (), and then click Edit tags.
Type new tags into the field and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags create TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
VERSION is version of the package that you want to tag.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to create the tag release-candidate for version 1.0.0 of package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags create release-candidate --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Updating tags

You can change a tag associated with a package version.

To change an existing tag:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
Click the package to view versions of the package.
Select the package version with the tag to change.
In the row of the selected version, click More actions (), and then click Edit tags.
Edit the tag and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags update TAG --package=PACKAGE \
    version=VERSION [--location=LOCATION] [--repository=REPOSITORY]

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
VERSION is version of the package that you want to tag.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to change the tag for version 1.0.0 of package my-package to production in the repository my-repo in the default location, run the command:

gcloud artifacts tags update production --version=1.0.0 \
    --package=my-pkg --repository=my-repo

Untagging package versions

You can remove an existing tag from a package version.

To remove a tag:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
Click the image to view versions of the image.
Select the image version to untag.
In the row of the selected version, click More actions (), and then click Edit tags.
Delete the tag and then click SAVE.

gcloud

Run the following command:

gcloud artifacts tags delete TAG --package=PACKAGE \
    [--location=<LOCATION] [--repository=REPOSITORY]

Where

TAG is the tag you want to apply to the package.
PACKAGE is the name of the package in the repository.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.

For example, to remove the tag release-candidate from package my-package in the repository my-repo in the default location, run the command:

gcloud artifacts tags delete release-candidate --package=my-pkg \
    --repository=my-repo

Installing packages

To install a package from the Node.js package repository:

If you are using the credential helper to authenticate with an access token, obtain a new token.
Use the npm install or yarn add command.
npm
To install version with the latest tag:
```
npm install @SCOPE/PACKAGE
```
To install version with a different tag:
```
npm install @SCOPE/PACKAGE@TAG
```
To install a specific version:
```
npm install @SCOPE/PACKAGE@VERSION
```
yarn
To install version with the latest tag:
```
yarn add @SCOPE/PACKAGE
```
To install version with a different tag:
```
yarn add @SCOPE/PACKAGE@TAG
```
To install a specific version:
```
yarn add @SCOPE/PACKAGE@VERSION
```
Replace the following values:
- SCOPE is the scope associated with the repository. If your Node.js package repository is not configured with a scope, omit @SCOPE/ from the command.
- PACKAGE is the name of the package in the repository.
- TAG is tag for the version you want to install.
- VERSION is the version number you want to install.

When you specify a package as a dependency in package.json, ensure that you include the scope for the repository. The following example shows the @dev-repo scope for a package named my-package.

"dependencies": {
  "@dev-repo/my-package": ">=1.0.0"
}

Deleting packages

After a package version is published, you cannot republish a package with the same name and version combination, even after deleting the version. This is an npm restriction to ensure that the contents of a published package version are always the same.

If you want to encourage users to install an updated package version, use the npm deprecate command to mark the old version of the package as deprecated. When a user tries to install the deprecated package, Artifact Registry returns a deprecation warning.

Before you delete a package or package version, verify that any you have communicated or addressed any important dependencies on it.

To delete a package:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
Select the package that you want to delete.
Click DELETE.
In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts packages delete PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] [--async]

Where

PACKAGE is the name of the package in the repository.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
--async Return immediately, without waiting for the operation in progress to complete.

To delete versions of a package:

Console

Open the Repositories page in the Google Cloud console.

Open the Repositories page
In the repository list, click the appropriate repository.

The Packages page lists the packages in the repository.
Click a package to view versions of that package.
Select versions that you want to delete.
Click DELETE.
In the confirmation dialog box, click DELETE.

gcloud

Run the following command:

gcloud artifacts versions delete VERSION \
    --package=PACKAGE \
    [--repository=REPOSITORY] [--location=LOCATION] \
    [--async]

Where

PACKAGE is the name of the package in the repository.
REPOSITORY is the name of the repository. If you configured a default repository, you can omit this flag to use the default.
LOCATION is a regional or multi-regional location. Use this flag to view repositories in a specific location. If you configured a default location, you can omit this flag to use the default.
--async returns immediately, without waiting for the operation in progress to complete.

Manage Node.js packages

Before you begin

Obtaining an access token

Adding packages

Viewing packages and versions

Console

gcloud

Listing files

Examples

Tagging packages

Viewing tags

Console

gcloud

Creating tags

Console

gcloud

Updating tags

Console

gcloud

Untagging package versions

Console

gcloud

Installing packages

npm

yarn

Deleting packages

Console

gcloud

Console

gcloud

What's next