How upstreams work

What happens when you pull a package with / without configured upstreams

If a registry is configured without any upstreams:

  • Developers can publish package versions to the private registry
  • Package versions can NOT be published from the private registry to public npm or any other registry
  • Installing packages from the registry requires the package version exists in the registry, else the installation fails

Adding an upstream to a registry enables a lot of different functions:

  • Packages can be published or pushed from the registry to the upstream
  • Packages not available in the registry can be pulled from the upstream and made available for the developer
  • Packages previously not available in the registry will be stored in the registry, caching and proxying the upstream

How npm install works with upstreams

Using npm install to add a package to your project is actually a three-step process.

  1. A list of all available versions for the package is downloaded and the result is combined by npm
  2. A specific version is chosen from the list
  3. Lastly the actual requested content is downloaded

For a registry without upstreams this request by the npm client will only be processed by the single registry.

When adding one or more upstreams on the other hand, the request for all available package versions will be passed along to all upstream registries and npm will receive information that includes the versions available in the upstream registries.

A version is lastly selected from this extended list of available package versions. If the requested version is not available in Bytesafe, it will be pulled from upstreams as needed.

If the package being installed is an internal package, only upstreams containing versions of the package flagged as internal will be considered (all other upstream sources will be hidden).

Upstream use cases and examples

How to best configure upstreams to suit an organization is not always straight forward.

Visit the Use cases section of the documentation for examples configurations as well as insight into ways upstreams can be used to automate work- and package flows.