Working with Node.js packages

Artifact Registry supports Node.js packages that you manage with npm.

Package management is in alpha. It is only available to alpha users, and might not include all features available for container management. To apply for the alpha, complete the sign up form.

Overview

To get familiar with Node.js packages in Artifact Registry, you can try the quickstart.

When you are ready to learn more, read the following information:

  1. If you are new to npm, read about how the following concepts apply to your repositories:
  2. Create an npm repository for your packages.
  3. Grant permissions to account that will connect with the repository. Service accounts for common integrations with Artifact Registry have default permissions for repositories in the same project.
  4. Configure npm to authenticate with the repository.
  5. Learn about managing packages.

Using scopes

An npm scope is a label that acts as a namespace. In the context of Artifact Registry, you can associate a scope with a repository to distinguish it from other repositories or other registries, such as the public npm registry.

If you are only working with a single npm repository, you do not need to use a scope. A registry that is not associated with a scope is configured like the following example in the .npmrc configuration file:

registry=https://us-central1-npm.pkg.dev/my-project/my-npm-repo/
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:_authToken=""
//us-central1-npm.pkg.dev/my-project/my-npm-repo/:always-auth=true

If you use a mixture of registries with npm, you must use scoped packages. For example, you might use both the public npm registry for open source packages and npm repositories in Artifact Registry for private packages.

Scopes are also useful when you want to work with multiple npm repositories in either the same project or across different Google Cloud projects. You can associate a scope with each repository in .npmrc and use the same credentials for authentication across the repositories.

The following example shows configuration for two Artifact Registry repositories in different projects.

  • The @blue scope is for the repository in the project blue-project.
  • The @green scope is for the repository in the project green-project.
@blue:registry=https://us-central1-npm.pkg.dev/blue-project/blue-npm-repo/
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:_authToken=""
//us-central1-npm.pkg.dev/blue-project/blue-npm-repo/:always-auth=true

@green:registry=https://us-central1-npm.pkg.dev/green-project/green-npm-repo/
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:_authToken=""
//us-central1-npm.pkg.dev/green-project/green-npm-repo/:always-auth=true

After you have authenticated to Artifact Registry, you can upload a package to a particular repository using the appropriate scope. For example, the following command uploads a package to the blue-npm-repo in the project blue-project:

npm publish @blue/blue-npm-repo

For more information about scopes, see the npm documentation

Where to store settings

Settings used for authentication are stored in npm configuration files. These files are named .npmrc. The following settings are used for Artifact Registry.

  • Credentials for the public npm registry

    Store your credentials for the public npm registry (https://registry.npmjs.org/) in the per-user config file so that they are not available to other users. This file is located in your user home directory, or is set with the npm --userconfig parameter or $NPM_CONFIG_USERCONFIG environment variable. The Artifact Registry tools for authenticating with Artifact Registry repositories are located in the public npm registry.

  • Settings for connecting to a repository

    You can store Artifact Registry repository settings in one of these npm configuration files:

    • The per-project config file. This .npmrc file is usually in the same directory as the package.json file in your npm project. This is the simpler option.

    • The per-user config file. This file is located in your user home directory, or is set with the npm --userconfig parameter or $NPM_CONFIG_USERCONFIG environment variable.

    • The global config file, $PREFIX/etc/npmrc. To get the value of $PREFIX, run the command npm prefix -g.

If you use both the public npm registry and an npm repository in Artifact Registry, all packages that you store in Artifact Registry repositories must be scoped and the default registry in the configuration file must be the public npm registry.

To check the current default registry value run the command:

npm get registry

To set the public npm registry as your default registry, run the command:

npm set registry https://registry.npmjs.org/

For more information about npm configuration files, see the npm config file documentation.