Quickstart for npm

Alpha

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.

This quickstart shows you how to set up an Artifact Registry npm repository and upload a package to it.

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. For more information, see Requirements to access alpha features.

Before you begin

1. Sign in to your Google Account.

   If you don't already have one, sign up for a new account.

2. In the Google Cloud Console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to the project selector page

3. Make sure that billing is enabled for your Cloud project. Learn how to confirm that billing is enabled for your project.

4. Enable the Artifact Registry API.

   Enable the API

5. Install and initialize the Cloud SDK.
6. Install PowerShell, if you want to connect to an npm repository from Windows.

Note: While billing must be enabled to use Artifact Registry, you are not charged for usage of Alpha repositories.

Create an npm repository

Create the repository for your Node.js artifacts.

1. Create the repository.

   Console

   1. Open the Repositories page in the Cloud Console.

      Open the Repositories page

   2. Click Create Repository.

   3. Specify quickstart-npm-repo as the repository name.

   4. Choose npm as the format.

   5. Under Location Type, select Region and then choose the location us-central1.

   6. Click Create.

   The repository is added to the repository list

   gcloud

   1. Run the following command to create a new npm repository named quickstart-npm-repo in the location us-central1 with the description "npm repository".

      gcloud artifacts repositories create quickstart-npm-repo --repository-format=npm \
      --location=us-central1 [--description="npm repository"]
      

   2. Run the following command to verify that your repository was created.

      gcloud artifacts repositories list
      

   For more information about Artifact Registry commands, run the command gcloud artifacts.

2. To simplify gcloud commands, set the default repository to quickstart-npm-repo and the default location to us-central1. After the values are set, you do not need to specify them in gcloud commands that require a repository or a location.

   To set the repository, run the command:

   gcloud config set artifacts/repository quickstart-npm-repo
   

   To set the location, run the command:

   gcloud config set artifacts/location us-central1
   

   For more information about these commands, see the gcloud config set documentation.

Set up a service account for your client

Create or choose an existing service account to act on behalf of npm.

1. Create a service account to act on behalf of your application, or choose an existing service account that you use for automation.

   You will need the location of the service account key file to set up authentication with Artifact Registry. For existing accounts, you can view keys and create new keys on the Service Accounts page.

   Go to the Service Accounts page

2. Grant the service account read and write access to your repository.

   gcloud artifacts repositories add-iam-policy-binding \
   quickstart-npm-repo --location=us-central1 --member='serviceAccount:ACCOUNT' --role='roles/artifactregistry.writer'
   

   Where ACCOUNT is the ID of your service account in the format [e-mail].

3. Assign the service account key file location to the variable GOOGLE_APPLICATION_CREDENTIALS so that the Artifact Registry credential helper can obtain your key when connecting with repositories.

   export GOOGLE_APPLICATION_CREDENTIALS=KEY-FILE
   

   Where KEY-FILE is path to the service account key file.

   To learn about setting up password authentication with the service account key file instead, see authentication#auth-password documentation.

Configure npm

1. Create an npm package to upload. If you don't have a package available to use with this quickstart, run the following command to create a plain package.json file:

   npm init -y
   

2. Configure your npm project to deploy to the Artifact Registry repository that you created.

   1. Run the following command. The command returns configuration settings to add to your npm configuration file.

      gcloud artifacts print-settings npm --scope=@quickstart
      

      The quickstart scope is associated with your repository. When you include the scope in commands to publish or install packages, npm uses your repository. When you publish or install packages without a scope, your configured default repository is used. For more information, see the Node.js overview.

      The output of the gcloud command looks like this:

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

   2. Add the configuration settings from the previous step to your project .npmrc file. The file is usually in the same directory as the package.json file.

      Replace PROJECT with your project ID.

      To learn more about the .npmrc file, see the Node.js overview.

Each Artifact Registry npm repository is associated with an npm registry endpoint https://LOCATION-npm.pkg.dev/PROJECT/REPOSITORY. If you create another Artifact Registry npm repository, npm interacts with it as a separate registry with its own scope.

Upload a package to the repository

1. Choose a package to upload. Ensure that package name in package.json includes the quickstart scope.

   "name": "@quickstart/my-package"
   

2. Refresh the access token for connecting to the repository. google-artifactregistry-auth is a client library that updates credentials for Artifact Registry repositories. To refresh credentials, use one of these options:

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

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

     Run the script with the command:

     npm run artifactregistry-login PROJECT-NPMRC
     

     Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

   • For versions of npm older than 5.2.0, perform the following steps:

     1. Run the command:

     npm install google-artifactregistry-auth --save-dev --registry https://registry.npmjs.org/
     

     1. Add it to an authentication script:

     "scripts": {
         "artifactregistry-login": "./node_modules/.bin/artifactregistry-auth",
     }
     

     Run the script with the command:

     npm run artifactregistry-login PROJECT-NPMRC
     

     Where PROJECT-NPMRC is the path to the .npmrc file in your project directory.

3. Add your package to the repository. You can use an npm or yarn command.

   npm publish
   

   yarn publish
   

View the package in the repository

To verify that your package was added to the repository:

Console

1. Open the Repositories page in the Cloud Console.

   Open the Repositories page

2. In the repository list, click the quickstart-npm-repo repository.

   The Packages page lists the packages in the repository.

3. Click on a package to view package versions.

gcloud

To list the images in the default quickstart-npm-repo repository, run the following command:

 gcloud artifacts packages list

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

gcloud artifacts versions list --package=PACKAGE

Where PACKAGE is the package ID.

Installing packages

To install a package from the npm repository, use the npm install or yarn add command. Replace PACKAGE with your package name.

npm install @quickstart/PACKAGE

yarn add @quickstart/PACKAGE

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, follow these steps.

Before you remove a repository, ensure that any packages that you want to keep are available in another location.

To delete the repository:

Console

1. Open the Repositories page in the Cloud Console.

   Open the Repositories page

2. In the repository list, select the quickstart-npm-repo repository.

3. Click Delete.

gcloud

1. To delete the quickstart-npm-repo repository, run the following command:

   gcloud artifacts repositories delete quickstart-npm-repo
   

2. If you want to remove the default repository and location settings that you configured for the active gcloud configuration, run the following commands:

   gcloud config unset artifacts/repository
   gcloud config unset artifacts/location
   

What's next

• Try the Maven quickstart
• Learn more about configuring authentication
• Learn about managing repositories
• Learn about managing packages
• Read our resources about DevOps and explore our research program.