Skip to main content
Version: Next

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/

Here's an example of seamlessly integrating npmjs and GitHub registries using Verdaccio: How to use Verdaccio with GitHub registry

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 # by defaults points to the environment variable `NPM_TOKEN`

or via a specified custom environment variable:

uplinks:
private:
url: https://private-registry.domain.com/registry
auth:
type: bearer
token_env: FOO_TOKEN # override the default `NPM_TOKEN` by a custom one

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

or by directly specifying a token oh the configuration file (not recommended by security corcerns):

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.
  • Multiple uplinks might slow down the lookup of your packages. For each request an npm client makes, verdaccio makes 1 call to each configured uplink.
  • The (timeout, maxage and fail_timeout) format follow the NGINX measurement units
  • When using the Helm Chart, you can use secretEnvVars to inject sensitive environment variables, which can be used to configure private uplink auth.