Merge pull request #8103 from MicrosoftDocs/artifacts/448715

JamesJBarnett · web-flow · commit 33a47627e5e8 · 2025-07-10T11:57:24.000-07:00
Npm feed auth
diff --git a/docs/artifacts/npm/npm-audit.md b/docs/artifacts/npm/npm-audit.md
@@ -34,7 +34,7 @@ This synchronization ensures that other projects sharing the same feed will also
     npm audit
     ```
 
-1. If you want to attempt to upgrade to non-vulnerable package versions, make sure you're [connected to your feed](./npmrc.md#connect-to-feed) first, then run the following command in your project directory:
+1. If you want to attempt to upgrade to non-vulnerable package versions, make sure you're [connected to your feed](npmrc.md#connect-to-a-feed) first, then run the following command in your project directory:
 
     ```Command
     npm audit fix
diff --git a/docs/artifacts/npm/npmrc.md b/docs/artifacts/npm/npmrc.md
@@ -1,38 +1,34 @@
 ---
-title: Connect your npm project to Azure Artifacts
-description: Learn how to set up your npm project and connect to Azure Artifacts
+title: Connect to an Azure Artifacts feed - npm
+description: Learn how to set up your npm project and connect to an Azure Artifacts feed.
 ms.assetid: A5364E3A-3918-4318-AAE0-430EA91AD5F1
 ms.service: azure-devops-artifacts
 ms.custom: engagement-fy23
 ms.topic: conceptual
-ms.date: 03/13/2025
+ms.date: 07/08/2025
 monikerRange: '>= azure-devops-2020'
 "recommendations": "true"
 ---
 
-# Connect your npm project to Azure Artifacts
+# Connect to an Azure Artifacts feed - npm
 
 [!INCLUDE [version-gt-eq-2020](../../includes/version-gt-eq-2020.md)]
 
-Azure Artifacts enables developers to manage their packages from various sources, including both public registries like npmjs.com and private feeds. To authenticate with Azure Artifacts, you'll need to configure your npm config file. This file contains feed URLs and credentials used by npm, offering options to customize your npm client behavior, such as setting up proxies, defining default package locations, or configuring private package feeds. The *npmrc* file is typically located in the user's home directory but can also be created at the project level to override default settings.
+Azure Artifacts enables developers to manage packages from various sources, including public registries like *npmjs.com* and private feeds. To authenticate with Azure Artifacts, you need to configure your *.npmrc* config file. This file stores feed URLs and credentials used by npm, and it allows you to customize client behavior such as setting up proxies, defining default package locations, or configuring access to private feeds. The *.npmrc* file is typically located in the user's home directory, but can also be created at the project level to override default settings.
 
 ## Prerequisites
 
-- An Azure DevOps organization. [Create one for free](../../organizations/accounts/create-organization.md).
+| **Product**        | **Requirements**   |
+|--------------------|--------------------|
+| **Azure DevOps**   | - An Azure DevOps [organization](../../organizations/accounts/create-organization.md).<br>- An Azure DevOps [project](../../organizations/projects/create-project.md).<br>- An Azure Artifacts [feed](../get-started-npm.md#create-a-feed)<br> - [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).|
 
-- An Azure DevOps project. Create a new [project](../../organizations/projects/create-project.md#create-a-project) if you don't have one already.
+## Connect to a feed
 
-- An Azure Artifacts feed. [Create one for free](../get-started-npm.md#create-a-feed).
+Azure Artifacts recommends using two separate *.npmrc* configuration files. One should be stored locally to store your credentials, while the other should be added to your project directory alongside your *package.json* to define your feed URL. This approach allows you to share your project-level configuration without exposing sensitive information.
 
-- [Download and install Node.js and npm](https://docs.npmjs.com/downloading-and-installing-node-js-and-npm).
+To set up the credentials file, create or update the *.npmrc* file and include all necessary registry credentials. This enables the npm client to easily access your credentials for authentication.
 
-## Connect to Feed
-
-Azure Artifacts recommends using two separate configuration files. The first is dedicated to authenticating with Azure Artifacts, while the second should be kept locally to store your credentials. This approach allows you to share your configuration file while keeping your credentials secure.
-
-To set up the second file, place it in your home directory on your development machine and include all your registry credentials. This enables the npm client to easily access your credentials for authentication.
-
-The following steps guide you through setting up the first configuration file. Select the tab that corresponds to your development environment:
+The following steps guide you through setting up the project-level configuration file. Select the tab that corresponds to your development environment:
 
 ::: moniker range="< azure-devops"
 
@@ -47,19 +43,31 @@ The following steps guide you through setting up the first configuration file. S
 
 1. Sign in to your Azure DevOps organization, and then navigate to your project.
 
-1. Select **Artifacts**, and then select **Connect to Feed**.
- 
-    :::image type="content" source="../media/npm-connect-to-feed-azure-devops.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Services.":::
+1. Select **Artifacts**, and then select your feed from the dropdown menu.
+
+1. Select **Connect to Feed** and then select **npm** from the left navigation pane. 
+
+1. Add a *.npmrc* to your project, in the same directory as your *package.json* and paste the provided snippet from the **Project setup** section into the file.
+
+    :::image type="content" source="../media/npm-project-setup-azure-devops.png" alt-text="A screenshot displaying how to set up your npm project and connect to a feed.":::
 
-1. Select **npm** from the left sidebar. If this is the first time using Azure Artifacts with npm, make sure you've installed the prerequisites.
+1. Run the following command to get an Azure Artifacts token added to your user-level *.npmrc* file. You don’t need to run this every time—npm will return a **401 Unauthorized** error when it’s time to refresh the token.
+
+    ```
+    vsts-npm-auth -config .npmrc
+    ```
+
+### [Other](#tab/other/)
+
+1. Sign in to your Azure DevOps organization, and then navigate to your project.
 
-1. Follow the instructions in the **Project setup** section to connect to your feed.
+1. Select **Artifacts**, and then select your feed from the dropdown menu.
 
-    :::image type="content" source="../media/npm-project-setup-azure-devops.png" alt-text="A screenshot showing how to set up your npm project.":::
+1. Select **Connect to Feed** and then select **npm** from the left navigation pane. 
 
-### [Linux/macOS](#tab/Linuxmac/)
+1. Add a *.npmrc* file to your project's directory. This should be the same directory where your *package.json* file is located. 
 
-1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the following snippet into it. 
+1. Paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following:
 
     ```
     registry=https://pkgs.dev.azure.com/<ORGANIZATION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/ 
@@ -99,19 +107,19 @@ The following steps guide you through setting up the first configuration file. S
 
 1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes.
 
-1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value.
+1. Run the following command in a command prompt window. When prompted, paste your personal access token (PAT) and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step.
 
     ```
     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(); })"
     ```
 
-1. If you're on Linux/Mac, you can alternatively use the following command to convert your personal access token to Base 64. Copy the resulting Base64 encoded value.
+1. If you're using Linux or macOS, you can run the following command in your terminal to convert your personal access token (PAT) to a Base64-encoded string. Copy the resulting value to use in the next step.
 
     ```
     echo -n "YOUR_PERSONAL_ACCESS-TOKEN" | base64
     ```
 
-1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step.
+1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step.
 
 * * *
 
@@ -123,23 +131,30 @@ The following steps guide you through setting up the first configuration file. S
 
 1. Sign in to your Azure DevOps collection, and then navigate to your project.
 
-1. Select **Artifacts**, and then select **Connect to Feed**.
+1. Select **Artifacts**, select your feed from the dropdown menu, and then select **Connect to Feed**.
  
     :::image type="content" source="../media/server-2022-1-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Server 2022.1.":::
 
-1. Select **npm** from the left sidebar, and then follow the instructions in the **Project setup** section to set up your config file.
+1. Select **npm** from the left, and then follow the steps in the **Project setup** section to configure your .npmrc. file and authenticate with your feed.
 
    :::image type="content" source="../media/npm-project-setup-server-2022-1.png" alt-text="A screenshot showing how to set up your npm project in Azure DevOps Server 2022.1.":::
 
-### [Linux/macOS](#tab/Linuxmac/)
+### [Other](#tab/other/)
 
-1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the following snippet into it. 
+1. Sign in to your Azure DevOps collection, and then navigate to your project.
+
+1. Select **Artifacts**, and then select your feed from the dropdown menu.
+
+1. Select **Connect to Feed** and then select **npm** from the left navigation pane. 
+
+1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following:
 
     ```
     registry=http://<SERVER_NAME>/<COLLECTION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/
                         
     always-auth=true
     ```
+
 ### Setup credentials
 
 1. Copy the following snippet and paste it into your user-level *.npmrc* file:
@@ -172,13 +187,13 @@ The following steps guide you through setting up the first configuration file. S
 
 1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes.
 
-1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value.
+1. Run the following command in a command prompt window. When prompted, paste your personal access token and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step.
 
     ```
     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(); })"
     ```
 
-1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step.
+1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step.
 
 * * *
 
@@ -194,13 +209,19 @@ The following steps guide you through setting up the first configuration file. S
  
     :::image type="content" source="../media/server-2020-1-connect-to-feed.png" alt-text="A screenshot showing how to connect to a feed in Azure DevOps Server 2020.1.":::
 
-1. Select **npm** from the left, and then follow the instructions in **Project setup** to set up your config file.
+1. Select **npm** from the left, and then follow the steps in the **Project setup** section to configure your .npmrc. file and authenticate with your feed.
 
    :::image type="content" source="../media/npm-project-setup-server-2020-1.png" alt-text="A screenshot showing how to set up your npm project in Azure DevOps Server 2020.1.":::
 
-### [Linux/macOS](#tab/Linuxmac/)
+### [Other](#tab/other/)
+
+1. Sign in to your Azure DevOps collection, and then navigate to your project.
 
-1. Add a *.npmrc* file in your project's directory, in the same directory as your package.json file, and paste the following snippet into it:
+1. Select **Artifacts**, and then select your feed from the dropdown menu.
+
+1. Select **Connect to Feed** and then select **npm** from the left navigation pane. 
+
+1. Add a *.npmrc* file in your project's directory, in the same directory as your *package.json* file, and paste the snippet provided in the **Project setup** section into your *.npmrc* file. Your file should look similar to the following:
 
     ```
     registry=http://<SERVER_NAME>/<COLLECTION_NAME>/<PROJECT_NAME>/_packaging/<FEED_NAME>/npm/registry/
@@ -209,7 +230,7 @@ The following steps guide you through setting up the first configuration file. S
     ```
 
 > [!NOTE]
-> For Debian, Ubuntu, and other community or entreprise distributions such as Fedora or Redhat make sure you've installed the prerequisites from the [NodeSource distributions repository](https://github.com/nodesource/distributions).
+> For Debian, Ubuntu, and other community or enterprise distributions such as Fedora or Redhat make sure you've installed the prerequisites from the [NodeSource distributions repository](https://github.com/nodesource/distributions).
 
 ### Setup credentials
 
@@ -243,73 +264,25 @@ The following steps guide you through setting up the first configuration file. S
 
 1. Generate a [personal access token](../../organizations/accounts/use-personal-access-tokens-to-authenticate.md) with **packaging read and write** scopes.
 
-1. Run the following command in a command prompt window, and then paste your personal access token when prompted. Once done, copy the generated Base 64 encoded value.
+1. Run the following command in a command prompt window. When prompted, paste your personal access token and press **Enter**. The script will return a Base64-encoded version of your PAT, copy that value to use in the next step.
 
     ```
     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(); })"
     ```
 
-1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user *.npmrc* file with the encoded personal access token obtained from the previous step.
+1. Replace the placeholders *[BASE64_ENCODED_PERSONAL_ACCESS_TOKEN]* in your user-level *.npmrc* file with the Base64-encoded personal access token you generated in the previous step.
 
 * * *
 
 ::: moniker-end
 
 > [!TIP]
-> Using multiple registries in .npmrc files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md).
-
-::: moniker range="azure-devops"   
-
-## Troubleshoot
-
-#### vsts-npm-auth is not recognized
-
-This error indicates that the npm modules folder hasn't been added to your path. Rerun the Node.js setup and make sure to select the `Add to PATH` option. Alternatively, you can add the npm modules folder to your path by modifying the PATH variable to `%APPDATA%\npm` in Command Prompt or `$env:APPDATA\npm` in PowerShell.
-
-:::image type="content" source="./media/node-setup.png" alt-text="A Screenshot showing how to set up node.js.":::  
-
-#### Unable to authenticate
-
-- 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 these steps to reset your vsts-npm-auth credentials:
-
-1. Uninstall vsts-npm-auth:
-
-    ```
-    npm uninstall -g vsts-npm-auth
-    ```
-
-1. Clear your npm cache:
-
-    ```
-    npm cache clean --force
-    ```
-
-1. Delete your *.npmrc* file.
-
-1. Reinstall vsts-npm-auth:
-
-    ```
-    npm install -g vsts-npm-auth --registry https://registry.npmjs.com --always-auth false
-    ```
-
-#### Unable to publish
-
-If you encounter a 403 error, it may indicate a name conflict. In Azure Artifacts, packages are immutable, meaning that once you publish a package to your feed, its version number is permanently reserved. Even if you delete it, you can't publish a new package with the same version number. To address this issue, update the package version in your *package.json* file, and then try again.
-
-::: moniker-end
+> Using multiple registries in *.npmrc* files is supported with [scopes](..//npm/scopes.md) and [upstream sources](../concepts/upstream-sources.md).
 
 ## Related content
 
-- [Publish npm packages (CLI)](./publish.md)
+- [Publish npm packages (CLI)](publish.md)
 
-- [Publish npm packages (YAML/Classic)](../../pipelines/artifacts/npm.md)
+- [Restore npm packages](restore-npm-packages.md)
 
-- [Use packages from npmjs.com](./upstream-sources.md)
+- [Publish npm packages with Azure Pipelines (YAML/Classic)](../../pipelines/artifacts/npm.md)
diff --git a/docs/artifacts/npm/publish.md b/docs/artifacts/npm/publish.md
@@ -46,7 +46,7 @@ If this is your first time using Azure Artifacts with npm on your machine, follo
 
 ## Publish packages
 
-1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-feed) to connect to your feed and then proceed with the next step once you're done.
+1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-a-feed) to connect to your feed and then proceed with the next step once you're done.
 
 1. Run the following command in your project directory to publish the npm packages listed in your *package.json*:
 
diff --git a/docs/artifacts/npm/restore-npm-packages.md b/docs/artifacts/npm/restore-npm-packages.md
@@ -43,7 +43,7 @@ If this is your first time using Azure Artifacts with npm on your machine, follo
 
 ## Restore packages
 
-1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-feed) to connect to your feed and then proceed with the next step once you're done.
+1. If you haven't authenticated with your feed yet, follow the steps in the [Project setup](npmrc.md#connect-to-a-feed) to connect to your feed and then proceed with the next step once you're done.
 
 1. Run the following command in your project directory to restore all your npm packages:
    
diff --git a/docs/artifacts/npm/upstream-sources.md b/docs/artifacts/npm/upstream-sources.md
@@ -54,7 +54,7 @@ If you checked the upstream sources checkbox during the creation of your feed, n
 
 ## Install packages from npmjs
 
-Before you save packages from npmjs, make sure your project is set up to connect to your feed. If you haven't done this yet, follow the provided instructions to [set up your npm project](npmrc.md#connect-to-feed) and connect to your feed. In this example, we'll install the *Axios* library for making HTTP requests:
+Before you save packages from npmjs, make sure your project is set up to connect to your feed. If you haven't done this yet, follow the provided instructions to [set up your npm project](npmrc.md#connect-to-a-feed) and connect to your feed. In this example, we'll install the *Axios* library for making HTTP requests:
 
 1. Navigate to npmjs at `https://www.npmjs.com//`.
 
