npmrc.md

title	description	ms.assetid	ms.technology	ms.topic	ms.date	monikerRange
Set up your client's npmrc	How to set up your project and authenticate to Azure Artifacts feeds	A5364E3A-3918-4318-AAE0-430EA91AD5F1	devops-artifacts	conceptual	03/16/2022	<= azure-devops

Set up your project and connect to Azure Artifacts

[!INCLUDE version-lt-eq-azure-devops]

With Azure Artifacts, you can publish different types of packages to your feeds such as npm, NuGet, Python, Maven, and Universal packages. You can also install packages from feeds and public registries such as npmjs.com. To authenticate with Azure Artifacts, we must first set up our config file. Npm uses .npmrc configuration files to store feed URLs and credentials.

Project setup

We recommend using two config files, the first one you should use to authenticate to Azure Artifacts, and the second one should be kept locally to store your credentials. On your development machine, place the second .npmrc file in your home directory. This second file should contain all your registries' credentials. The following steps will help set up your other config file:

::: moniker range=">= azure-devops-2019"

1. Select Artifacts, and then select Connect to feed.

   :::image type="content" source="../media/connect-to-feed-azure-devops-newnav.png" alt-text="Screenshot showing how to connect to a feed.":::

::: moniker-end

::: moniker range="tfs-2018"

1. Select Packages, and then select Connect to feed.

   :::image type="content" source="../media/connect-to-feed.png" alt-text="Screenshot showing how to connect to a feed in TFS.":::

::: moniker-end

2. Select npm from the list of package types.

3. If this is the first time using Azure Artifacts with npm, select Get the tools and follow the instructions to install the prerequisites.

::: moniker range="azure-devops"

4. Follow the instructions in Project setup to set up your config file.

   :::image type="content" source="../media/npm-azure-devops-newnav.png" alt-text="Screenshot showing the steps to set up the project and publish and restore packages.":::

::: moniker-end

::: moniker range="azure-devops-2019 || azure-devops-2020"

4. Follow the instructions in Project setup to set up your config file.

   :::image type="content" source="../media/connect-to-feed-devops-server.png" alt-text="Screenshot showing the steps to set up the project and restore packages.":::

::: moniker-end

::: moniker range="tfs-2018"

4. Follow the instructions to set up your project.

   :::image type="content" source="../media/connect-to-feed-npm-registry.png" alt-text="Screenshot showing the steps to set up the project in TFS.":::

::: moniker-end

Note

if your organization is using a firewall or a proxy server, make sure you allow the appropriate domain URLs. See Allowed IP addresses and domain URLs for more details.

Credentials setup

Tip

Multiple registries in .npmrc files are supported with upstream sources and scopes.

Windows

If you're developing on Windows, we recommend that you use vsts-npm-auth to fetch the credentials and inject them into your %USERPROFILE%\.npmrc. The easiest way to set this up is to install vsts-npm-auth globally and then add a run script to your package.json.

• Install vsts-npm-auth globally:

  npm install -g vsts-npm-auth

• Add script to package.json:

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

Linux/Mac

vsts-npm-auth is not supported in Linux/Mac. Follow the steps below to set up your credentials:

1. Copy the following snippet into your npmrc file.

   • Organization-scoped feed:

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:username=[ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/_packaging/<FEED_NAME>/npm/:email=npm requires email to be set but doesn't use the value
     ; end auth token

   • Project-scoped feed:

     ; begin auth token
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/:email=npm requires email to be set but doesn't use the value
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:username=[ENTER_ANY_VALUE_BUT_NOT_AN_EMPTY_STRING]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/:_password=[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]
     //pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/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. Encode your newly generated personal access token as follows:

   1. Run the following command in an elevated command prompt window, and then paste your personal access token when prompted:

      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(); })"

      You can also use the following command to convert your personal access token to Base64:

      • LinuxMac:

        echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64

   2. Copy the Base64 encoded value.

4. Open your .npmrc file and replace the placeholder [BASE64_ENCODED_PERSONAL_ACCESS_TOKEN] with your encoded personal access token that you created in the previous step.

---

Note

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

Authentication setup

Azure Artifacts recommend using the npmAuthenticate task to set up authentication for your pipeline tasks. When using a task runner such as gulp or Grunt, you'll need to add the npm Authenticate task at the beginning of your pipeline. This will inject your credentials into your project's .npmrc and persist them for the lifespan of the pipeline run. This allows subsequent steps to use the credentials in the config file.

Classic

::: moniker range=">= azure-devops-2019"

1. Select Azure Pipelines, and then select your pipeline definition.

2. Select Edit to modify your pipeline.

3. Select + to add a task to your pipeline.

   [!div class="mx-imgBorder"]

4. Search for the npm Authenticate task, and then select Add to add it to your pipeline.

   [!div class="mx-imgBorder"]

5. Select your .npmrc file.

   [!div class="mx-imgBorder"]

6. Select Save & queue when you're done.

::: moniker-end

::: moniker range="tfs-2018"

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

   [!div class="mx-imgBorder"]

2. Select your pipeline, and then select Edit.

3. Select + to add a task to your pipeline.

   [!div class="mx-imgBorder"]

4. Search for the npm Authenticate task, and then select Add to add it to your pipeline.

   [!div class="mx-imgBorder"]

5. Select your .npmrc file.

   [!div class="mx-imgBorder"]

6. Select Save & queue when you're done.

::: moniker-end

YAML

- task: npmAuthenticate@0
  inputs:
    workingFile: .npmrc
    customEndpoint: #Optional
- script: npm ci

• workingFile: Path to the npmrc file
• customEndpoint: Comma-separated list of npm service connection names for registries from external organizations. For registries in your org, leave this blank

---

Tip

To allow your pipeline access to your feed, make sure you give the build service a Contributor role in your feed's settings. Select Azure Artifacts -> [YOUR_FEED] -> Settings -> Permissions -> set the build service role to Contributor.

[!div class="mx-imgBorder"]

Troubleshoot

vsts-npm-auth is not recognized

If you're running into the following error:

• Cmd: '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 the Node.js setup and make sure that the Add to PATH options are selected.

[!div class="mx-imgBorder"]

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

Unable to authenticate

If you're running into a E401 error: code E401 npm ERR! Unable to authenticate. Run the vsts-npm-auth command with -F flag to reauthenticate.

vsts-npm-auth -config .npmrc -F

Reset vsts-npm-auth

Follow the steps below to modify/reset your vsts-npm-auth credentials:

• Uninstall vsts-npm-auth.

  npm uninstall -g vsts-npm-auth

• Clear your npm cache.

  npm cache clean --force

• Delete your .npmrc file.

• Reinstall vsts-npm-auth.

  npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false

Related articles

• Publish npm packages (YAML/Classic)
• Use npm scopes
• Use npm audit