Quickstart: Use npm to store JavaScript packages in VSTS or TFS

VSTS | TFS 2018 | TFS 2017

This tutorial is an end-to-end guide on using npm to store JavaScript packages using Visual Studio Team Services or Team Foundation Server. It covers installation, license assigning, and setup.

Step 1: Install and license the Package Management extension

Package Management is an extension that must be installed from the Marketplace.

Install Package Management extension

  1. Go to the Marketplace page for Package Management

  2. Select Get

    Package Management extension for VSTS in Visual Studio Marketplace

  3. Select your account into which the Package Management extension should be installed

  4. Each account gets five (5) free licenses. If you need more than 5 licenses, click Buy and purchase the additional licenses you need. If you aren't sure you can click Start 30 day free trial and every user in your account will be granted access to Package Management for 30 days. After the 30-day trial period your account will revert back to five (5) entitled users and you must assign licenses to individual users. If you need additional licenses at this point, you may purchase them from this same dialog in the Marketplace.

  5. After the install is completed, select Proceed to the account. Then, go to any project and select the Packages hub in the Build & Release hub group

Assign licenses

If you selected Start 30 day free trial and are still in the trial period, every user is granted access and licenses do not need to be assigned until the trial period has ended.

If you selected Buy or Get it free, you will need to assign your licenses by following the instructions below:

  1. Go to your account, select the Users hub, and select Package Management.
  2. Select Assign, type the users you want to assign licenses to, then select Ok.

    If you have a Visual Studio Enterprise license, you already have access to Package Management and don't need to be assigned a license, just ensure that you've been assigned the "Visual Studio Enterprise" access level.

Step 2: Create a feed

On your first visit to the Packages hub in the Build and Release hub group, you'll be welcomed with an image telling you to create a new feed, click the + New feed button.

In the dialog:

  • Give the feed a name.
  • Visibility: Choose who can read and contribute (or update) packages in your feed. An account visible feed is created with permissions that allow all users in the account to see/use your feed (recommended). A private feed is created with permissions such that only you have access.
  • Upstream sources: Clicking Use packages from public sources through this feed will add both the public NPM (registry.npmjs.org) and NuGet (packages.nuget.org) as upstreams to your feed. When upstreams are enabled your client (i.e. npm and nuget) will be able to fetch packages from the public registry through your private feed and your private feed will cache those packages for you. If you select Use packages published to this feed your feed will be created without connectivity to public registries. You can connect them at a later date if you desire.
  • When you're done, choose Create.

New feed dialog

You can change these settings later by editing the feed.

Step 3: Set up your npmrc

All Package Management 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?

VSTS recommends using two .npmrc files:

  1. One .npmrc should live at the root of your git repo adjacent to your project's package.json. It should contain a "registry" line for your feed and it should not contain credentials since it will be checked into git. You can find the registry information for your feed from the Connect to Feed button:

    1. From your Packages page, click Connect to Feed

      Connect to feed from VSTS Package Management

    2. Copy the "registry" text:

      Connect to feed from VSTS Package Management

  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

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

IMPORTANT: There can only be a single "registry=" line in your .npmrc. Multiple registries are possible with scopes and our new upstream feature (discussed here).

Windows

If you are developing on Windows, we recommend that you use vsts-npm-auth to fetch credentials and inject them into your ~/.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

For Linux or Mac users, the Connect to feed dialog will generate an appropriately-formatted token that you can place into your .npmrc file with a lifespan of 90 days.

If you want to create a token that lasts longer than 90 days, skip to the second method below.

90-day token:

  1. From the Packages hub, select Connect to feed

  2. Select npm.

  3. Click Generate npm credentials and copy them to add them to your user .npmrc manually:

    Connect to feed from VSTS Package Management Linux/Mac credentials

Create a token that lasts longer than 90 days:

  1. Navigate to security and generate a PAT with a narrow scope of "Packaging (read and write)".
  2. Base64 encode the PAT. On Windows you can use...

    [Convert]::ToBase64String([system.Text.Encoding]::UTF8.GetBytes("YOUR_PAT_GOES_HERE"))
    
  3. In your $home/.npmrc add the following lines replacing account, feedname, username, PAT, and email.

    //<youraccount>.pkgs.visualstudio.com/_packaging/<yourfeed>/npm/registry/:username=YOUR-USERNAME
    //<youraccount>.pkgs.visualstudio.com/_packaging/<yourfeed>/npm/registry/:_password=BASE64-ENCODED-PAT-GOES-HERE
    //<youraccount>.pkgs.visualstudio.com/_packaging/<yourfeed>/npm/registry/:email=YOUREMAIL@EXAMPLE.COM
    //<youraccount>.pkgs.visualstudio.com/_packaging/<yourfeed>/npm/registry/:always-auth=true
    

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. Add a build definition in VSTS under the Build and Release --> Builds hub.

    Connect to feed from VSTS Package Management

  2. Choose your source Team project, Repository, and Default branch and select Continue

  3. Select Empty process at the top of the form

  4. Add a task to Phase 1 of your build definition by clicking the "+":

    Add task to build definition

  5. Select Package or search for npm in the search bar, select npm and select Add:

    Add task to build definition

  6. Select the npm install task underneath Phase 1:

    Add task to build definition

  7. Browse to and select your Working folder with package.json:

    Add task to build definition

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

    • Registries in my .npmrc

      Add task to build definition

      You can choose credentials to authenticate to outside of your current account/collection by setting up service endpoints.

    • Registry I select here

      Add task to build definition

      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.

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 definition. This will inject credentials into your proejct's .npmrc and persist them for the lifespan of the build. This allows subsequent build steps to use the credentials in the .npmrc.

  1. Add a build definition in VSTS under the Build and Release --> Builds hub.

    Connect to feed from VSTS Package Management

  2. Choose your source Team project, Repository, and Default branch and select Continue

  3. Select Empty process at the top of the form

  4. Add a task to Phase 1 of your build definition by clicking the "+":

    Add task to build definition

  5. Select Package or search for npm in the search bar, select npm Authenticate and select Add:

    Add task to build definition

  6. Select the npm Authenticate task underneath Phase 1:

    Add task to build definition

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

    Add task to build definition

    You can choose credentials to authenticate to outside of your current account/collection by setting up service endpoints.

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

Step 4: Use packages from npmjs.com

In addition to packages you publish, you can use packages from www.npmjs.com through this feed via upstream sources. Because this feed was created with public registries enabled (see Step 2), you should be able to use packages from an upstream source. To try it out, just run an npm install command (e.g. npm install lodash) in a shell opened to your project's folder. Learn more about upstream sources on the upstream sources concepts page.

You can choose to enable or disable upstream sources in the Settings -> Upstream sources tab:

Upstream sources

Step 5: Build your project

At this point your project should have a package.json and an .npmrc that are adjacent to each other. You should run npm install from the directory that contains both of these files. Npm will discover your feed in the .npmrc in the current working directory and will fetch credentials from your home directory's .npmrc that you configured in Step 2.

Step 6: Publish an npm package

If you have followed all of the steps up to this point, you can publish by:

  1. Navigating to the directory that contains your package's package.json file
  2. Run npm publish

npm publish will work because of the credentials you acquired in Step 3.

If you have followed all of the steps up to this point package publishing should simply work. There are, however, some important considerations:

  • If you have npmjs.com configured as an upstream and the package name/version exists in the public registry then you will be blocked from publication. We do not support overriding packages that exist on the public registry.