Skip to main content

Uplinks

An uplink is a link with an external registry that provides access to external packages.

Uplinks

Usage#

uplinks:  npmjs:   url: https://registry.npmjs.org/  server2:    url: http://mirror.local.net/    timeout: 100ms  server3:    url: http://mirror2.local.net:9000/  baduplink:    url: http://localhost:55666/

Configuration#

You can define mutiple uplinks and each of them must have an unique name (key). They can have the following properties:

PropertyTypeRequiredExampleSupportDescriptionDefault
urlstringYeshttps://registry.npmjs.org/allThe registry urlnpmjs
castringNo~./ssl/client.crt'allSSL path certificateNo default
timeoutstringNo100msallset new timeout for the request30s
maxagestringNo10mallthe time threshold to the cache is valid2m
fail_timeoutstringNo10malldefines max time when a request becomes a failure5m
max_failsnumberNo2alllimit maximun failure request2
cachebooleanNo[true,false]>= 2.1cache all remote tarballs in storagetrue
authlistNosee below>= 2.5assigns the header 'Authorization' more infodisabled
headerslistNoauthorization: "Bearer SecretJWToken=="alllist of custom headers for the uplinkdisabled
strict_sslbooleanNo[true,false]>= 3.0If true, requires SSL certificates be valid.true
agent_optionsobjectNomaxSockets: 10>= 4.0.2options for the HTTP or HTTPS Agent responsible for managing uplink connection persistence and reuse more infoNo default

Auth property#

The auth property allows you to use an auth token with an uplink. Using the default environment variable:

uplinks:  private:    url: https://private-registry.domain.com/registry    auth:      type: bearer      token_env: true # defaults to `process.env['NPM_TOKEN']`

or via a specified environment variable:

uplinks:  private:    url: https://private-registry.domain.com/registry    auth:      type: bearer      token_env: FOO_TOKEN

token_env: FOO_TOKEN internally will use process.env['FOO_TOKEN']

or by directly specifying a token:

uplinks:  private:    url: https://private-registry.domain.com/registry    auth:      type: bearer      token: "token"

Note: token has priority over token_env

You Must know#

  • Uplinks must be registries compatible with the npm endpoints. Eg: verdaccio, sinopia@1.4.0, npmjs registry, yarn registry, JFrog, Nexus and more.
  • Setting cache to false will help to save space in your hard drive. This will avoid store tarballs but it will keep metadata in folders.
  • Exceed with multiple uplinks might slow down the lookup of your packages due for each request a npm client does, verdaccio does 1 call for each uplink.
  • The (timeout, maxage and fail_timeout) format follow the NGINX measurement units