Set up your client's npmrc

Azure DevOps Services | TFS 2018 | TFS 2017

Azure Artifacts is an extension to Azure DevOps Services and Azure DevOps Server that makes it easy to discover, install, and publish different types of packages. Check out Start using Azure Artifacts for more details.

All Azure Artifacts feeds require authentication, so you'll need to store credentials for the feed before you can install or publish packages. npm uses .npmrc configuration files to store feed URLs and credentials.

Where are my .npmrc files?

Azure DevOps Services recommends using two .npmrc files:

  1. One .npmrc should live at the root of your git repo adjacent to your project's package.json.

    1. From your Packages page, click Connect to Feed

      Connect to feed button in Azure Artifacts Azure Devops

      Connect to feed TFS

    2. Select npm.

    3. Select Get the tools in the top-right corner.

    1. Follow steps 1 and 2 to download Node.js, npm, and the artifacts credential provider.

    2. Follow the instructions under the Project setup section to set up your project. See the Restore packages and Publish packages sections if you want to publish or restore your packages.

      Connect to feed DevOps services

    1. Follow the instructions in the Project setup and Restore packages sections.

      Connect to feed server 2019 and 2020

    1. Follow steps 1 and 2 to download Node.js, npm, and the artifacts credential provider.

    2. Follow the instructions under the Project setup section to set up your project. See the Restore packages and Publish packages sections if you want to publish or restore your packages.

      Connect to feed TFS project setup

  2. On your development machine, you will also have a .npmrc in $HOME for Linux or Mac systems or $env.HOME for win systems. This .npmrc should contain credentials for all of the registries that you need to connect to. The NPM client will look at your project's .npmrc, discover the registry, and fetch matching credentials from $HOME/.npmrc or $env.HOME/.npmrc. Credential acquisition will be discussed in the next section.

This enables you to share project's .npmrc with the whole team while keeping your credentials secure.

Set up authentication on your dev box

You should have a project specific .npmrc containing only your feed's registry information that you discovered from the "Connects to Feed" dialog. There should be no credentials in this file and the file itself is adjacent to your project's package.json.

Important

There can only be a single "registry=" line in your .npmrc. Multiple registries are possible with upstream sources, or by using scopes (not recommended).

Windows

If you are developing on Windows, we recommend that you use vsts-npm-auth to fetch credentials and inject them into your %USERPROFILE%\.npmrc on a periodic basis. The easiest way to set this up is to install vsts-npm-auth globally (i.e. npm install -g vsts-npm-auth) and then add a run script in your project's package.json.

"scripts": {
    "refreshVSToken" : "vsts-npm-auth -config .npmrc"
}

Linux or Mac

If you are developing on Linux or Mac, vsts-npm-auth is not supported and we recommend generating a token in the following manner for your $HOME/.npmrc

Project setup

The Connect to feed dialog box generates an appropriately formatted token that you can place into your .npmrc file. The token has a lifespan of 90 days.

Tip

If you want to create a token that lasts longer than 90 days, make sure you change the default expiration date.

  1. From Azure Artifacts, select Connect to feed.

  2. Select npm.

  3. Select Other in the Project setup section.

    Screenshot of the connect to feed credentials.

  4. Add a .npmrc file to your project, in the same directory as your package.json file.

    registry=https://pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/registry/
    
    always-auth=true
    

Credentials setup

  1. Copy the following code to your user .npmrc file.

    ; begin auth token
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/registry/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/registry/:email=npm requires email to be set but doesn't use the value
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
    //pkgs.dev.azure.com/<yourOrganization>/_packaging/<yourFeed>/npm/:email=npm requires email to be set but doesn't use the value
    ; end auth token
    
  2. Generate a personal access token, with packaging read and write scopes.

  3. Base64 encode the personal access token from the previous step. Then safely encode your personal access token:

    1. From a command prompt, run the following:

      node -e "require('readline') .createInterface({input:process.stdin,output:process.stdout,historySize:0}) .question('PAT> ',p => { b64=Buffer.from(p.trim()).toString('base64');console.log(b64);process.exit(); })"
      

      Other options to convert your personal access token to Base64:

      Windows:

      [Convert]::ToBase64String([system.Text.Encoding]::UTF8.GetBytes("YOUR_PAT_GOES_HERE"))
      

      Linux/Mac:

      echo -n "YOUR_PAT_GOES_HERE" | base64
      
    2. Paste your personal access token value, and press Enter or Return.

    3. Copy the Base64 encoded value.

  4. Replace both [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] values in your user .npmrc file with your Base64 encoded personal access token from the previous step. You should also replace yourOrganization and yourFeed, and fill in your username, your personal access token, and email.

  1. From Packages, select Connect to feed.

  2. Select npm.

  3. Select Generate npm credentials. Copy the credentials to add them to your user .npmrc file manually:

    Screenshot of the connect to npm feed.

vsts-npm-auth is not supported on on-premises TFS and Azure DevOps Server.

To work with packages from Azure Artifacts, set up your project to reference this feed. Create a new text file .npmrc in the same directory as your package.json and copy the snippet below:

@[YOUR_SCOPE]/registry=FabrikamBasic/_packaging/FabrikamFeed/npm/registry/

To restore your packages, run the following command in your project directory:

npm install

Set up authentication in a build task

There are two options for setting up authentication in a build task:

Without a Task Runner

To set up npm authentication in a build task without a task runner, follow the directions below.

  1. Select Azure Pipelines, it should automatically take you to the Builds page.

    navigate to builds tab TFS

  2. Create a new pipeline.

    create new build pipeline

  3. Choose your source Project, Repository, and Default branch and select Continue.

  4. Start with an Empty job.

  5. On the left side, select the plus sign ( + ) to add a task to Job 1. On the right side, select the Package category, select the npm task from the list, and then choose Add.

    build tab add task to job

  6. Select the npm install task, then browse to and select your Working folder with package.json:

    Add npm install task to build pipeline

  7. Expand Custom registries and authentication, here you have a few options:

    • Registries in my .npmrc

      registries in the npmrc file

      Note

      You can choose credentials to authenticate to services outside of your current organization/collection by setting up service connections.

    • Registry I select here

      Registries to use

      When you choose this option, the task will create a temporary .npmrc with credentials for the registry you've selected and it will override the project's .npmrc. This is useful when you want to publish to a specific feed.

  8. Select Save & queue, and then select Save.

Tip

If your NPM Install build task is failing with Error 403, then make sure you set your build service as a contributor. To do so, go to Azure Artifacts -> Select your feed -> Settings -> Permissions -> set your build service role to contributor.

tip screenshot

  1. Select Build and Release, and then choose Builds.

    navigate to builds tab TFS 2018

  2. Create a new pipeline.

    create new pipeline

  3. Choose your source Project, Repository, and Default branch and select Continue.

  4. Start with an Empty job.

  5. On the left side, select the plus sign ( + ) to add a task to Job 1. On the right side, select the Package category, select the npm task from the list, and then choose Add.

    builds tab add npm task to job

  6. Select the npm install task, then browse to and select your Working folder with package.json:

    Add npm install task

  7. Expand Custom registries and authentication, here you have a few options:

    • Registries in my .npmrc

      registries in the npmrc

      Note

      You can choose credentials to authenticate to services outside of your current organization/collection by setting up service connections.

    • Registry I select here

      registry I select here option

      When you choose this option, the task will create a temporary .npmrc with credentials for the registry you've selected and it will override the project's .npmrc. This is useful when you want to publish to a specific feed.

  8. Select Save & queue, and then select Save.

With a Task Runner (e.g. make gulp work)

When using a task runner, you'll need to add the npm Authenticate build task at the beginning of your build pipeline. This will inject credentials into your project's .npmrc and persist them for the lifespan of the build. This allows subsequent build steps to use the credentials in the .npmrc.

  1. Select Azure Pipelines, it should automatically take you to the Builds page.

    navigate to builds tab TFS 2018 second

  2. Create a new pipeline.

    new build pipeline

  3. Choose your source Project, Repository, and Default branch and select Continue.

  4. Start with an Empty job.

  5. On the left side, select the plus sign ( + ) to add a task to Job 1. On the right side, select the Package category, select the npm Authenticate task from the list, and then choose Add.

    builds tab add npm task

  6. Select the npm Authenticate task underneath Phase 1:

    npm auth task phase

  7. Browse to and select your .npmrc file to authenticate:

    npm auth task

    Note

    You can choose credentials to authenticate to services outside of your current organization/collection by setting up service connections.

  8. After setting up your npm Authenticate task, you can add other build task(s) for your task runner like Gulp.

  1. Select Build and Release, and then choose Builds.

    navigate to builds tab team foundation services

  2. Create a new pipeline.

    new build pipeline button

  3. Choose your source Project, Repository, and Default branch and select Continue.

  4. Start with an Empty job.

  5. On the left side, select the plus sign ( + ) to add a task to Job 1. On the right side, select the Package category, select the npm Authenticate task from the list, and then choose Add.

    builds-tab-add-task-to-job

  6. Select the npm Authenticate task underneath Phase 1:

    phase one npm auth

  7. Browse to and select your npmrc file to authenticate:

    npmrc file to authenticate

    Note

    You can choose credentials to authenticate to services outside of your current organization/collection by setting up service connections.

  8. After setting up your npm Authenticate task, you can add other build task(s) for your task runner like Gulp.

Troubleshooting vsts-npm-auth

If you receive an error like:

  • Command Prompt: 'vsts-npm-auth' is not recognized as an internal or external command, operable program or batch file.
  • PowerShell: vsts-npm-auth : The term 'vsts-npm-auth' is not recognized as the name of a cmdlet, function, script file, or operable program.

then it's likely that the npm modules folder is not in your path.

To fix this issue, rerun Node.js setup and ensure the Add to PATH option and its child options are selected for installation.

Add to PATH install option in Node.js setup

Alternatively, you can edit the PATH variable to add %APPDATA%\npm (Command Prompt) or $env:APPDATA\npm (PowerShell).

Next steps