Skip to main content

Best Practices

The following guide is a list of the best practices collected and that we usually recommend to all users. Do not take this guide as mandatory, you might pick some of them according your needs.

Feel free to suggest your best practices to the Verdaccio community.

Private Registry​

You can add users and manage which users can access which packages.

It is recommended that you define a prefix for your private packages, for example local-* or scoped @my-company/*, so all your private things will look like this: local-foo. This way you can clearly separate public packages from private ones.

 packages:
   '@my-company/*':
     access: $all
     publish: $authenticated
    'local-*':
     access: $all
     publish: $authenticated
   '@*/*':
     access: $all
     publish: $authenticated
   '**':
     access: $all
     publish: $authenticated

Always remember, the order of packages access is important, packages are matched always top to bottom.

Using public packages from npmjs.org​

If a package doesn't exist in the storage, the server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from the cache pretending that no other packages exist. Verdaccio will download only what's needed (requested by clients), and this information will be cached, so if the client requests the same thing a second time it can be served without asking npmjs.org for it.

Example:

If you successfully request express@4.0.1 from the server once, you'll be able to do it again (with all of it's dependencies) any time, even if npmjs.org is down. Though note that express@4.0.0 will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, the server will say that only express@4.0.1 (what's in the cache) is published, but nothing else.

Override public packages​

If you want to use a modified version of some public package foo, you can just publish it to your local server, so when your type npm install foo, it'll consider installing your version.

There's two options here:

  1. You want to create a separate fork and stop synchronizing with public version.

    If you want to do that, you should modify your configuration file so Verdaccio won't make requests regarding this package to npmjs anymore. Add a separate entry for this package to config.yaml and remove npmjs from proxy list and restart the server.

    packages:
      '@my-company/*':
        access: $all
        publish: $authenticated
        # comment it out or leave it empty
        # proxy:

    When you publish your package locally, you should probably start with a version string higher than the existing package so it won't conflict with that package in the cache.

  2. You want to temporarily use your version, but return to the public one as soon as it's updated.

    In order to avoid version conflicts, you should use a custom pre-release suffix of the next patch version. For example, if a public package has version 0.1.2, you can upload 0.1.3-my-temp-fix.

     npm version 0.1.3-my-temp-fix
     npm publish --tag fix --registry http://localhost:4873

    This way your package will be used until its original maintainer updates his public package to 0.1.3.

Security​

Security starts in your environment.

Additional reading:

Strong package access with $authenticated​

By default all packages you publish in Verdaccio are accessible for all users. We recommend protecting your registry from external non-authorized users by updating the access property of your packages to $authenticated.

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
  '@*/*':
    access: $authenticated
    publish: $authenticated
  '**':
    access: $authenticated
    publish: $authenticated

That way, nobody can access your registry unless they are authorized, and private packages won't be displayed in the web interface.

Require a second factor for publishing​

Experimental

Requires Verdaccio 7.x or later, not 6.x. To evaluate it, use the 9.x experimental line (verdaccio@next-9), where it lands first.

Not recommended for production yet — the advice below is what we think good practice looks like once the feature settles, and trying it out is exactly the feedback that gets it there.

A leaked or committed token is enough to publish in someone's name. Enabling two-factor authentication in auth-and-writes mode means a token alone is no longer enough — publishing also needs a code from the maintainer's authenticator:

flags:
  tfa: true

Turning the flag on does not enable anything by itself; each user opts in with npm profile enable-2fa auth-and-writes.

Two things to plan for before rolling this out to a team:

  • Publishing from CI breaks, because a pipeline cannot produce a code. Either publish from an account in auth-only mode, or pair this with staged publishing (below), which is designed for exactly that case.
  • Rotating the server secret locks every enrolled user out, with no self-service recovery. Ask users to disable two-factor before a rotation.

Review releases before they are installable​

Experimental

Requires Verdaccio 7.x or later, not 6.x. To evaluate it, use the 9.x experimental line (verdaccio@next-9), where it lands first.

Not recommended for production yet — the advice below is what we think good practice looks like once the feature settles, and trying it out is exactly the feedback that gets it there.

Protecting who can publish still means the publish takes effect immediately. Staged publishing adds a review step: the version is uploaded but nobody can install it until a maintainer inspects the tarball and approves it.

flags:
  stage: true

packages:
  '@my-company/*':
    access: $authenticated
    stage: developers
    publish: release-managers

The stage permission is what makes this a control rather than a convention. Granting it to a group that does not have publish means those users can propose a release but cannot make one, and cannot approve their own submission. Leave stage out and it falls back to publish, in which case the same person can stage and approve — convenient, but it enforces nothing.

This also solves the CI problem above: npm stage publish never asks for a one-time password, so a pipeline can prepare a release that a maintainer approves with theirs.

Remove proxy to increase security at private packages​

After a clean installation, by default all packages will be resolved to the default uplink (the public registry npmjs).

packages:
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

This means that even if a private package like @my-company/auth is published locally, the server will look up at the public registry. If that's not your intention, remove the proxy property and use a configuration like this one:

packages:
  '@my-company/*':
    access: $authenticated
    publish: $authenticated
    unpublish: $authenticated
  '@*/*':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs
  '**':
    access: $authenticated
    publish: $authenticated
    proxy: npmjs

This will avoid downloading tarballs, and merge metadata needlessly from external registries.

Server​

Secured Connections​

Using HTTPS is a common recommendation. For this reason we recommend reading the SSL section to make Verdaccio secure, or alternatively using an HTTPS reverse proxy on top of Verdaccio.

Expiring Tokens​

Tokens have no expiration date by default. Enabling JWT gives them one:

security:
  api:
    jwt:
      sign:
        expiresIn: 15d
        notBefore: 0
  web:
    sign:
      expiresIn: 1h

Using this configuration will override the current system and you will be able to control how long the token will live.

Using JWT also improves the performance with authentication plugins. The old system will perform an unpackage and validate the credentials on every request, while JWT will rely on the token signature instead, avoiding the overhead for the plugin.

As a side note, be aware at npmjs and the legacy verdaccio token never expires** unless you invalidate manually.

Rate Limit​

Critical endpoints have rate limiting enabled by default. The following commands are considered user endpoints:

  • npm token all variants
  • npm login/adduser
  • npm profile all supported variants
  • User website /sec/login endpoint.

The previous list of endpoints are limited to 100 request peer 15 minutes which is enough for a basic usage, if you need to increase this levels please check the userRateLimit configuration options.

userRateLimit:
  windowMs: 50000 <- (minutes * 60 * 1000)
  max: 1000 (number of request peer windowMs)

The website endpoints as, search, packages, sidebar, and detail are protected by default to 5,000 request peer 2 minutes, also configurable via web ui options.

We recommend customize this values to those that addapt your needs to avoid any kind of (DDoS) or brute-force attack to the critical endpoints.

The CLI API endpoints used by eg npm install are not limited at this point since are not considered critical, but if you find any good reason please open a discussion.

Edit this page
Last updated on by Juan Picado (jotadeveloper)