Working with Node.js packages

Preview

This product or feature is covered by the Pre-GA Offerings Terms of the Google Cloud Platform Terms of Service. Pre-GA products and features may have limited support, and changes to pre-GA products and features may not be compatible with other pre-GA versions. For more information, see the launch stage descriptions.

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

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 the following concepts:
   • npm scopes
   • the .npmrc configuration file
2. Create a Node.js package repository for your packages.
3. Grant permissions to the 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 for grouping packages. Scopes are necessary when you are working with multiple npm registries, including:

• Publishing and installing packages in different registries without the need to switch from one registry to another. For example, your builds might include packages from both the public npm registry and an Artifact Registry repository.
• Publishing the same packages to multiple Artifact Registry repositories across Google Cloud projects, as well as other npm registries, without package name conflicts.

We recommend that you always set a scope for your repositories. If you do not specify a scope when you publish or install package, npm uses the configured default registry, such as the public npm registry.

You set the scope for each Artifact Registry repository in the .npmrc configuration file. The same credentials for authentication apply 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

Storing credentials

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 an Artifact Registry repositories

  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 simplest 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.

You should retain any existing default registry configured in your .npmrc file. The default is typically set to the public npm registry at https://registry.npmjs.org/.

To check the current default registry value run the command:

npm get registry

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