Use packages from

Last Update: 3/17/2017

Team Services | TFS 2017 Update 1

The npm client is designed to work with a single primary registry (what Package Management calls a feed). It also supports secondary scoped registries. Scoped registries can only be used to install packages whose names begin with the scope prefix, so their usage is more restrictive. If you want to use both private packages you've created and public packages from, we recommend using upstream sources.

Upstream sources

Upstream sources allow you to merge the contents of into your feed such that the npm client can install packages from both locations. Enabling upstream sources also automatically enables caching. This is the recommended way to use Package Management with npm. Upstreams give you the most flexibility to use a combination of scoped- and non-scoped packages in your feed, as well as scoped- and non-scoped packages from

Enable as an upstream

To enable as an upstream source on your feed, check the box in the Create Feed or Edit Feed dialog.

Upstream sources checkbox in New feed dialog

Upstream sources checkbox in Edit feed dialog

Order and shadowing

When a feed with upstreams enabled receives a query (e.g. npm install lodash), it will first check for local packages with that package ID. If there is at least one local version of that package ID, the upstream source will not be used. So, for example, if you publish lodash@1.0.0 and run npm install lodash@2.0.0, the request will fail, even if 2.0.0 exists on and upstream sources are enabled.

Shadowing is permanent. So, in the example above, even if you later unpublish lodash@1.0.0, requests for any lodash version will only check the local feed.


When you enable as an upstream source, packages installed from will automatically be cached in your feed.These packages could be installed directly from the upstream (e.g. npm install lodash) or as dependencies of packages that reside in your feed.

Caching can improve download performance and save network bandwidth, esp. for TFS servers located on internal/dedicated networks.

Internet requirements

When you run an npm install command, the feed will check to see if it has a cache of the package(s) requested by the npm client. If it does not, it will redirect the client to download the package from directly, and also cache the package in the background. The first client (where client is a developer machine or a build agent) to install a given npm package will need Internet access to successfully retrieve the package or they will have to run npm install twice. The first install will fail but cause the package to be cached; the second install will return the package from the cache.

If you host your own build agents, they do not need access to the Internet for this feature. However, per the limitation above, a developer machine will need to first run npm install to cache the package(s) so that they're available to the build agents.

For TFS users, the TFS server must be able to access the domain in order to cache packages.

Filtering to cached packages

You can see the packages you have cached in your feed by selecting the "Source = cache" filter.

Viewing your cached packages

No guarantee of caching

Right now, VSTS and TFS do not provide a guarantee that every package npm installed via a feed with upstreams enabled will be cached.

Packages with malformed version numbers in their packages.json cannot be ingested into the feed, and thus must still be retrieved directly from If goes down, you are not fully protected if you depend on these packages.

In a future sprint, we'll be updating the upstreams feature to always cache and serve packages through the feed. In the rare case where a package cannot be cached, the install will fail (without redirecting to so that you have full confidence that every package you use is cached by your feed.


If you prefer to use scopes, which limit your private packages to those with the @<scope> prefix e.g. @fabrikam/core but enable you to consume public packages directly from, see Scopes.