Publishing Packages

Your account’s main registry hosts your private packages. On a private account, every package published to it must be scoped to your account slug — for example, an account with the slug acme publishes packages named @acme/utils, @acme/app, and so on.

The registry speaks the npm registry protocol, so you can publish with whichever package manager you already use.

Guides

Each guide covers configuring the package manager against your account’s two registries, installing from both, and publishing to main — along with the version requirements and gotchas specific to that tool. They use acme as the account slug; replace it with your own, or use the Setup Instructions button in the dashboard’s Registries section, which generates them for your account.

vlt vlt 1.0

npm npm 12

pnpm pnpm 10, 11 and 12

yarn Yarn 4 (Berry) and Yarn Classic

bun bun 1.4

deno deno 2.9

CI & automation Unattended installs and publishes with a service token

Whichever client you use, you’ll need to authenticate — see Authentication & Tokens.

What the registry validates

Your package manager packs the package into a tarball and uploads it along with its manifest. The registry then validates every publish:

• On a private account, the package name must be scoped to your account: @acme/utils publishes, but an unscoped name like utils, or a name under someone else’s scope like @other-team/utils, is rejected with a 403 Forbidden error.
• The name and version in the request, the manifest, and the tarball’s package.json must all agree, which protects consumers against manifest confusion.
• The tarball’s integrity hash is recomputed and verified on the server.
• Tarballs are limited to 100 MB by default.

Versions are immutable

Exactly one version is published at a time, and once a version is published it can never be replaced. Publishing an existing version again fails with a conflict error. If you unpublish a version, that version number is permanently reserved and cannot be reused — publish a new version instead.

Dist-tags

If you don’t specify a tag, a publish updates latest. Use a tag to publish pre-releases without affecting the default install:

Terminal

$ vlt publish --tag=beta

Tags can only reference versions that exist, and the standard npm dist-tag endpoints are supported for listing, adding, and removing tags.

Two-factor authentication

By default, accounts require a one-time password (OTP) for publishes and other package writes made with a personal token. When the registry asks for it, your client opens a browser where you confirm the write with the second factor enrolled on your vlt.io account. You’ll need one enrolled before your first publish.

Service tokens are not subject to the OTP prompt, which is what makes unattended publishes from CI possible — see CI & automation. Account owners and admins can adjust the two-factor requirement under Settings → General.

Note

The vlt registry does not currently support OIDC trusted publishing. Use a service token in CI.

Deprecating and unpublishing

Deprecation and unpublish follow the standard npm protocol, so vlt deprecate and vlt unpublish — and their npm equivalents — work against your registry. Deprecating a version attaches a warning message that installers display; it can be reversed by deprecating again with an empty message. Unpublishing removes a version (or an entire package), and as noted above, unpublished version numbers can never be reused.

Package visibility

By default, packages on a private account’s main registry are readable only by members of that account. Individual packages can be made public, which makes them installable by anyone — with no token at all, and no auth line in the consumer’s config. Each guide above shows the minimal configuration a public package needs.

Set the level when you publish:

Terminal

$ vlt publish --access=public

Or record it with the package, so it doesn’t depend on who runs the publish. Every package manager in the guides above reads this field:

package.json

{
"name": "@acme/utils",
"publishConfig": { "access": "public" }
}

To read or change the level of a package that’s already published:

Terminal

$ vlt access get status @acme/utils
$ vlt access set status=restricted @acme/utils
$ vlt access list packages @acme

The two levels are public and restricted. Access changes made with a personal token are subject to the same OTP requirement as a publish.

Teams can also be granted read-only or read-write access to individual packages with vlt access grant and vlt access revoke — see Members & Access Control.