npm

The minimum supported npm version is 10. Every supported Verdaccio requires a Node.js release that already bundles npm 10 or 11, so older clients are neither tested nor supported.

Some features need more than that: npm stage requires npm 11.17. Verdaccio supports it as an experimental feature, and it is worth a try — see staged publishing below.

Setting up global registry for all projects

To set the registry for all your local projects in any terminal window run:

npm set registry http://localhost:4873/

This will set the registry for your operational system user and you can find it on the file ~/.npmrc.

Using registry for a specific project

To set this value for a specific project open its root folder on a terminal window and run:

npm set registry http://localhost:4873/ --location project

This will set the registry in a .npmrc file in your project root directory.

or by specific scope eg: @my-scope/auth:

npm config set @my-scope:registry http://localhost:4873

Using registry only on specific command

If you want one single use append --registry http://localhost:4873/ to the required command. Some examples:

npm ci --registry http://localhost:4873
npm install --registry http://localhost:4873
npm install lodash --registry http://localhost:4873

How to prevent your package from being published in other registries

If you only want to publish your package to Verdaccio but keep installing from other registries you can setup the publishConfig in your package.json as described in the official documentation.

{
  "publishConfig": {
    "registry": "http://localhost:4873"
  }
}

Creating user

Since npm@9 the two commands do separate things, which is the behaviour on every supported version:

• login authenticates an existing user and does not create one:

npm login --registry http://localhost:4873

• adduser creates a user and does not log them in:

npm adduser --registry http://localhost:4873

Both rely on web login by default; adding --auth-type=legacy gets the previous behaviour back.

On npm@8 and older, either command both created the user and logged them in. Those versions are no longer supported.

Web login is not supported for verdaccio.

Two-factor authentication

Depends on the registry

Requires the tfa feature flag enabled on the Verdaccio side. It is experimental, off by default, and available from 7.x — it does not exist in 6.x. To try it, run the 9.x experimental line (verdaccio@next-9), which is where it lands first. Not recommended for production yet. Nothing is configured on the npm side.

With the flag enabled you can protect your account with a time-based one-time password using the standard npm commands:

npm profile enable-2fa auth-and-writes
npm profile get                          # two-factor auth: auth-and-writes
npm profile disable-2fa

Which commands ask for a code depends on the mode you enrol in. Both auth-only and auth-and-writes ask when you log in or create a token; only auth-and-writes asks again on every write.

So with auth-only, npm publish never asks for a code even though two-factor is on. The second factor guards the door rather than each write, which is what keeps a pipeline working: a person creates the token once, with their code, and CI publishes with that token afterwards. The trade-off is that a leaked token can publish.

With auth-and-writes, publishing asks. npm prompts for the code in an interactive terminal; in a script pass it directly:

npm publish --otp=123456

Without a TTY and without --otp, npm fails with EOTP rather than hanging. A code is single use and lives about ninety seconds, so it cannot be stored in a CI secret — to keep auth-and-writes and still release from a pipeline, see staged publishing below.

See two-factor authentication for the full table of what each mode asks for, recovery codes, and what happens if the server secret is rotated.

Staged publishing

Depends on the registry

Requires the stage feature flag enabled on the Verdaccio side. It is experimental, off by default, and available from 7.x — it does not exist in 6.x. To try it, run the 9.x experimental line (verdaccio@next-9), which is where it lands first. Not recommended for production yet. With the flag off, the npm stage commands answer 404.

With the flag enabled, npm stage uploads a version for review instead of publishing it outright. It only becomes installable once a maintainer approves it.

npm stage publish            # upload for review, nothing is installable yet
npm stage list               # see what is waiting
npm stage download <id>      # inspect the tarball before deciding
npm stage approve <id>       # publish it for real
npm stage reject <id>        # discard it

These commands require npm 11.17 or newer. They do not exist in earlier versions, and there is no Yarn or pnpm equivalent.

npm stage publish never asks for a one-time password, in either two-factor mode, which is what lets a CI pipeline prepare a release that a human approves later with theirs.

That pairing is the answer to the CI problem above: keep auth-and-writes, let the pipeline stage without a code, and require the code at npm stage approve, where there is a person to type it. Every write stays protected and nothing needs a code stored in a secret.

See staged publishing for the full flow and the permissions involved.

Hiding recently published versions

npm can refuse versions published less than N days ago, as a supply-chain precaution:

.npmrc

min-release-age=7
min-release-age-exclude[]=@my-company/*

Unlike pnpm and Yarn, npm leaves this off by default — it is null in npm 11 and still null in npm 12 — so you only meet it if someone turned it on. When it is on and you publish to Verdaccio and install straight away, the version is filtered and npm reports:

npm error code ENOVERSIONS
npm error No versions available for @my-company/widget

which reads as if the package had no versions at all. Exempt your own packages with min-release-age-exclude, or pass --min-release-age=0 for a single command.

The unit is days here

min-release-age counts days, while pnpm's minimumReleaseAge and Yarn's npmMinimalAgeGate count minutes. 1 means a day in npm and a minute in the others.

It also affects npm audit fix: when the patched version is too recent, npm keeps the vulnerable one, warns that the fix was blocked, and exits non-zero.

Troubleshooting

npm login with npm@9 or higher

If you are running into issues login with npm@9.x or higher you could try use the legacy mode (see above).

For progress on the native support on future you can track the following issue#3413.

SSL and certificates

When using Verdaccio under SSL without a valid certificate, defining strict-ssl in your config file is required otherwise you will get SSL Error: SELF_SIGNED_CERT_IN_CHAIN errors.

npm does not support invalid certificates anymore since 2014.

npm config set ca ""
npm config set strict-ssl false

Mixed registries in lockefile (npm v7+)

Since version 7 npm got more strict with the introduction of lockfileVersion: 2. If you have mixed resolved fields in your lockfile, for instance, having this in your lockfile:

{
  "name": "npm7",
  "version": "1.0.0",
  "lockfileVersion": 2,
  "requires": true,
  "packages": {
    "": {
      "version": "1.0.0",
      "license": "ISC",
      "dependencies": {
        "lodash": "4.17.20",
        "underscore": "^1.11.0"
      }
    },
    ..... // removed for simplicity
  },
  "dependencies": {
    "lodash": {
      "version": "4.17.20",
      "resolved": "https://registry.npmjs.org/lodash/-/lodash-4.17.20.tgz",
      "integrity": "sha512-PlhdFcillOINfeV7Ni6oF1TAEayyZBoZ8bcshTHqOYJYlrqzRK5hagpagky5o4HfCzzd1TRkXPMFq6cKk9rGmA=="
    },
    "underscore": {
      "version": "1.11.0",
      "resolved": "http://localhost:4873/underscore/-/underscore-1.11.0.tgz",
      "integrity": "sha512-xY96SsN3NA461qIRKZ/+qox37YXPtSBswMGfiNptr+wrt6ds4HaMw23TP612fEyGekRE6LNRiLYr/aqbHXNedw=="
    }
  }
}

Either running npm i --registry https://registry.npmjs.org or using .npmrc will fail your installation.