yarn

Yarn 4.15 hides packages published in the last day

Yarn has a npmMinimalAgeGate setting: a version published more recently than the gate is refused. It arrived in 4.10 switched off, and since 4.15 it defaults to 1d — one day. A package you just published to Verdaccio and try to install straight away is therefore invisible, which looks like the version does not exist.

Keep the protection and exempt your own scope, or the specific packages:

.yarnrc.yml
npmScopes:
  my-company:
    npmMinimalAgeGate: 0

# or by name, including glob patterns
npmPreapprovedPackages:
  - '@my-company/*'

Setting npmMinimalAgeGate: 0 at the top level turns it off entirely, which is what a throwaway registry in CI wants.

One more thing worth knowing: Yarn quarantines a version whose publish date it cannot read, not just one that is too recent. Verdaccio does record a time entry per version, so this works — but a storage plugin that drops time would block every install with the gate on.

Setting up the registry

Yarn modern does not recognize --registry or .npmrc file anymore.

For defining a registry you must use the .yarnrc.yml located in the root of your project or global configuration.

When you publish a package the npmRegistryServer must be used. Keep in mind the publishConfig.registry in the package.json will override this configuration.

// .yarnrc.yml
npmRegistryServer: "http://localhost:4873"

unsafeHttpWhitelist:
  - localhost

unsafeHttpWhitelist is only need it if you don't use https with a valid certificate.

Using scopes is also possible and more segmented, you can define a token peer scope if is required.

npmRegistries:
  "https://registry.myverdaccio.org":
    npmAlwaysAuth: true
    npmAuthToken: <TOKEN>
npmScopes:
  my-company:
    npmRegistryServer: https://registry.myverdaccio.org
    npmPublishRegistry: https://registry.myverdaccio.org

for logging via CLi use:

yarn npm login --scope my-company

Extra registry commands

Yarn 4 ships a smaller set of registry commands than npm. There is no yarn npm ping, no yarn npm unpublish, no yarn npm deprecate and no yarn npm star, and yarn npm login only speaks the web flow.

verdaccio/yarn-plugin-npm is a set of Yarn 4 plugins that add them. They are maintained by the Verdaccio team and work against any npm-compatible registry, not only Verdaccio.

Experimental

These plugins are experimental and still on 0.0.x. Commands, flags and output may change between releases, so pin a version if you depend on them in CI.

Feedback is what moves them forward. If you try them, tell us which commands you actually needed, what behaved differently from npm, and what is still missing: open a thread in GitHub Discussions or come to Discord. Reports about what does not work are the most useful ones at this stage.

Installing

The quickest way is the importer, which downloads a plugin and registers it in your .yarnrc.yml:

yarn dlx @verdaccio/yarn-import npm-ping
yarn dlx @verdaccio/yarn-import npm-login
yarn dlx @verdaccio/yarn-import npm-unpublish
yarn dlx @verdaccio/yarn-import npm-deprecate
yarn dlx @verdaccio/yarn-import npm-star

Pin a version by appending it: yarn dlx @verdaccio/yarn-import npm-ping 0.0.1.

Check what is installed with yarn plugin list.

Requires Yarn 4.x and Node.js >= 24.

What each one adds

Plugin	Commands
`npm-ping`	`yarn npm ping`
`npm-login`	`yarn npm login` with a legacy flow
`npm-unpublish`	`yarn npm unpublish`
`npm-deprecate`	`yarn npm deprecate`
`npm-star`	`yarn npm star`, `yarn npm unstar`

All of them accept --registry <url>, --scope <scope> and --json.

yarn npm ping --registry http://localhost:4873
yarn npm unpublish my-package@1.0.0
yarn npm unpublish my-package --force            # every version
yarn npm deprecate my-package@"<2.0.0" "Upgrade to v2"
yarn npm deprecate my-package@1.0.0 ""           # un-deprecate
yarn npm star lodash

The built-in yarn npm login assumes the web flow, which is the source of the long-standing friction listed under known issues. The npm-login plugin adds --auth-type, so you can ask for the legacy username/password exchange that a self-hosted Verdaccio understands:

yarn npm login --auth-type=legacy --registry http://localhost:4873

--auth-type=auto is the default and tries the web flow first, falling back to legacy on 404/501. For CI, pass the credentials directly instead of being prompted:

yarn npm login --auth-type=legacy \
  --user "$NPM_USER" --password "$NPM_PASS" --email "$NPM_EMAIL"

Note the legacy flow creates users on registries that accept CouchDB user documents; logging in as an existing user only works when the registry exposes revision metadata without Basic authentication.

Two-factor authentication

Depends on the registry

This only applies when the operator has enabled the tfa feature flag on the Verdaccio side. It is an experimental flag, off by default, and available from 7.x; to try it, run the 9.x experimental line (verdaccio@next-9), which is where it lands first. Not recommended for production yet. See two-factor authentication.

Nothing is configured on the Yarn side.

When the registry has it enabled and your account is enrolled, Yarn handles the one-time password on its own and prompts for it:

yarn npm publish
# Provide a one-time password from your authenticator app.
# One-time password: ‹

The unpublish and deprecate plugins above also take --otp <code> for non-interactive use.

Enrolling still has to be done with npm — npm profile enable-2fa — since Yarn has no equivalent command.

Staged publishing

Not available in Yarn

Staged publishing is driven by npm stage, which is an npm command with no Yarn equivalent. Even with the stage feature flag enabled on the registry, a Yarn-based workflow cannot stage or approve versions — the registry endpoints are there, but no Yarn command calls them.

Publishing normally with yarn npm publish keeps working as usual, and is not affected by the flag.

Troubleshooting

Known issues

yarn npm login issues, read verdaccio#1737 or yarn-berry#1848.
yarn npm publish does not send README, read verdaccio#1905 or yarn-berry#1702.

`yarn` classic (1.x)

No longer maintained

Yarn 1.x has been in maintenance since Yarn 2 and receives no new features. Everything above assumes Yarn 4; if you are still on classic, migrating is the better use of your time than configuring it.

Classic reads .npmrc, so the npm instructions apply, and it also has its own .yarnrc:

registry "http://localhost:4873"

The one classic-specific trap: it does not send the authorization header on yarn install unless always-auth is on, so private packages fail to resolve until you set it:

npm config set always-auth true

Note that always-auth is itself deprecated in modern npm, which is a fair summary of where this combination stands.

Setting up the registry​

Extra registry commands​

Installing​

What each one adds​

Logging in to a self-hosted registry​

Two-factor authentication​

Staged publishing​

Troubleshooting​

Known issues​

yarn classic (1.x)​