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 with the Verdaccio community.
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.
Always remember, the order of packages access is important, packages are mached always top to bottom.
Using public packages from npmjs.org
If some package doesn't exist in the storage, server will try to fetch it from npmjs.org. If npmjs.org is down, it serves packages from 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 client will ask the same thing second time, it can be served without asking npmjs.org for it.
If you successfully request
firstname.lastname@example.org from this server once, you'll able to do that again (with all it's dependencies) anytime even if npmjs.org is down. But say
email@example.com will not be downloaded until it's actually needed by somebody. And if npmjs.org is offline, this server would say that only
firstname.lastname@example.org (= only 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:
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
proxylist and restart the server.
# comment it out or leave it empty
When you publish your package locally, you should probably start with version string higher than existing one, so it won't conflict with existing package in the cache.
You want to temporarily use your version, but return to 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
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
Security starts in your environment.
- 10 npm Security Best Practices and following the steps outlined there.
- Avoiding npm substitution attacks
- Dependency Confusion: When Are Your npm Packages Vulnerable?
- Practical Mitigations For Dependency Confusion Attack > Feel free to attach here new useful articles to improve the security.
Strong package access with
By default all packages you publish in Verdaccio are accessible for all users. By default all packages are you publish in Verdaccio are accessible for all public, we totally recommend protect your registry from external non authorized users updating
access property to
In that way, nobody will take advance of your registry unless is authorized and private packages won't be displayed in the User Interface.
proxy to increase security at private packages
This means, if a private packaged eg:
@my-company/auth is published locally, the registry will look up at the public registry. If your intention is fully protection, remove the
proxy property from your configuration, for instance:
This configuration will avoid downloading needlessly to external registries, merging external metadata and download external tarballs.
email@example.com the tokens have no expiration date. For such reason we introduced in the next
firstname.lastname@example.org the JWT feature PR#896
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. Using JWT also improves the performance with authentication plugins, the old system will perform an unpackage and validating the credentials in each request, while JWT will rely on the token signature avoiding the overhead for the plugin.
As a side note, at npmjs the token never expires.
v5.4.0 critical endpoints have enabled by default rate limit. The following commands are considered user endpoints:
npm tokenall variants
npm profileall supported variants
- User website
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.
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 installare not limited at this point since are not considered critical, but if you find any good reason please open a discussion.