Get started with npm packages in Azure Artifacts

Azure Artifacts supports publishing and consuming npm packages to and from Azure Artifacts feeds and public registries. Use this quickstart to create your feed, set up your .npmrc file, build your project, and publish your npm packages to your feed.

License the Azure Artifacts extension

To use Azure Artifacts, you must upgrade to Visual Studio Team Foundation Server 2017. If the Azure Artifacts extension has been removed, you can install it from Visual Studio Marketplace.

Assign licenses in Team Foundation Server

Each organization gets five free licenses. If you need more than five licenses, go to Visual Studio Marketplace, and select Get it free.

If you aren't sure, you can select Start 30-day free trial. Every user in your organization is then granted access to Azure Artifacts for 30 days. After the 30-day trial period, your organization reverts back to five entitled users, and you must assign licenses to individual users. If you need additional licenses at this point, you can purchase them from Visual Studio Marketplace. If you have a license for Visual Studio Enterprise, you already have access to Azure Artifacts and don't need to be assigned a license. Just ensure that you've been assigned the "Visual Studio Enterprise" access level.

Note

If you selected Start 30 day free trial and are still in the trial period, every user is granted access. Licenses don't need to be assigned until the trial period ends.

  1. From any collection in Team Foundation Server, hover over the settings menu and select Users. Then select Package Management.

    Screenshot of the Users page in Team Foundation Server.

  2. Select Assign, enter the users you want to assign licenses, and then select OK.

    • Users with Visual Studio Enterprise subscriptions get Azure Artifacts for free. Make sure that your Visual Studio Enterprise subscribers have the appropriate access level. For more information, see Change access levels.

    • Users who are using an instance of Team Foundation Server that's disconnected from the internet (and thus can't purchase licenses from Visual Studio Marketplace) can still assign licenses purchased through an enterprise agreement.

Create a feed

A feed is an organizational construct that allows users to store packages and control who can access them by modifying the feed permissions.

Feeds aren't dependent on the type of package. Azure Artifacts currently supports storing NuGet, npm, Maven, Python, and Universal packages in a single feed.

To create a new feed, select Create feed from within your feed, and fill out the form.

  • Name: The feed name.
  • Visibility: Choose who can upload or download packages to or from your feed.
  • Upstream sources: If you want to add upstream sources to your feed such as npmjs.org or NuGet.org, select Include packages from common public sources. When upstream sources are enabled, your client can fetch packages from the public registry through your private feed, and your private feed will cache those packages for you. If you want to create your feed without connectivity to public registries, clear the Upstream sources check box. You can add them later if you choose to.

When you're done, select Create.

Screenshot of the new feed dialog box in Azure DevOps 2019.

Screenshot of the new feed dialog box in Team Foundation Server.

You can change these settings later by editing the feed.

With your feed selected, select the gear icon (on the right side of the page).

Screenshot of the Edit feed button.

Screenshot of the Edit feed button.

Set up your .npmrc files

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

Note

vsts-npm-auth isn't supported on on-premises Team Foundation Server and Azure DevOps Server.

Find your .npmrc files

We recommend that you use two .npmrc files:

  1. One .npmrc should live at the root of your Git repo where your project's package.json file is located.

    1. From Artifacts, select Connect to feed.

      Screenshot that shows how to connect to your feed.

    2. Select npm > Get the tools.

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

    4. Select Windows if you're on a Windows Machine, or Other if you're on macOS or Linux.

    5. Follow the instructions in the Project setup, Restore packages, and Publish packages sections.

      Screenshot that shows the setup, restore, and publish sections to connect your feed.

  2. On your development machine, you also have a .npmrc file in the $home folder for Linux or Mac systems, or in $env.HOME for Windows. This .npmrc file should contain credentials for all of the registries that you need to connect to. The NPM client looks at your project's .npmrc file, discovers the registry, and fetches matching credentials from $home/.npmrc or $env.HOME/.npmrc.

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

Set up authentication on your development machine

At this point, you should have a project-specific .npmrc file. This file contains only your feed's registry information that you discovered from the Connect to feed dialog box. There should be no credentials in this file. The file is usually stored in the same location as your project's package.json file.

Important

There can be only a single registry= line in your .npmrc file. Multiple registries are possible with scopes and upstream sources.

Windows

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

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

Linux/Mac

If you're developing on Linux or Mac, vsts-npm-auth isn't supported. Instead, generate a token in the following manner for your $HOME/.npmrc file.

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.

Build your project

At this point, your project should have a package.json file and a .npmrc file in the same folder. Run npm install from the directory that contains both of these files. npm discovers your feed in the .npmrc file in the current working directory. It then fetches the credentials from your home directory's .npmrc file that you configured in the "Create a feed" section.

Publish npm packages

You can now publish the npm package:

  1. Browse to the directory that contains your package's package.json file.

  2. Run npm publish.

This command authenticates to the feed by using the .npmrc configuration files that you had to set up earlier. For more information, see the npm CLI docs.

Your npm package should now be available in your feed.

Important

Ensure that your working folder has an .npmrc file with a registry= line, as described in the Connect to feed screen in your feed. The build doesn't support using the publishConfig property to specify the registry to which you're publishing. If you include the publishConfig property in your package.json file, the build might fail with an unrelated authentication error.

Download npm packages

You can install npm packages from your Azure Artifacts feed or the public registry.

  1. Set up your client's npmrc.

  2. open an elevated command prompt window and navigate to the directory that contains your package.json file.

  3. Install a package by running this command:

    npm install --save <package>
    

For more details, see the npm-install docs.

Next steps