Configuring

VSR (vlt’s Serverless Registry) is compatible with multiple package managers, allowing you to use your preferred tooling while benefiting from VSR’s features. This guide covers configuration for various package managers and deployment scenarios.

Setting up your VSR instance

VSR can be configured to work with any npm-compatible package manager. The configuration approach varies depending on which package manager you’re using and your specific workflow requirements.

There are two primary configuration methods:

1. Custom registry protocol - Recommended for fine-grained control over package sources
2. Default registry replacement - Simpler setup for complete registry switching

Choose the method that best fits your workflow and security requirements.

Getting started with VSR

For this example we’re going to use a local-running VSR instance. Here’s how to start one:

Terminal

$ npx -y vltpkg/vsr

For production deployment, use the new vsr deploy command:

Terminal

$ vsr deploy --env=prod

See our Deployment Guide for complete deployment instructions.

Please note, in the rest of this guide you may need to replace http://localhost:1337 with the correct URL of your VSR instance (local or deployed).

Log in to your VSR instance. In case you already have a custom user token configured than you should just use that. If you’re just getting started and want to test using the default admin profile you may just use the default token: xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx.

Terminal

$ vlt token --registry=http://localhost:1337 add

The token subcommand is going to open a prompt allowing you to input the user token.

Please note that the default admin token is not suitable for regular usage, do not use it outside of just a simple experimental test setup.

Set up a VSR instance using a custom registry protocol

Edit your config file to set the local VSR instance as a valid custom registry protocol:

vlt.json

{
  "registries": {
    "vsr": "http://localhost:1337"
  }
}

It’s now possible to install specific packages from your VSR instance using vsr: as a package alias. In the following example we’re going to install a package named foo that was published to our custom VSR instance:

Terminal

$ vlt install foo@vsr:foo@latest

Here is how the resulting package.json may look like:

package.json

{
  "name": "my-project",
  "version": "1.0.0",
  "dependencies": {
    "foo": "vsr:foo@^1.0.0"
  }
}

Set up a VSR instance as the default registry

Set the local VSR instance as the default registry:

Terminal

$ vlt config set registry=http://localhost:1337

Alternatively, you can also edit your config file:

vlt.json

{
  "registry": "http://localhost:1337"
}

Using the default registry setup, each vlt install <pkg> will fetch assets from your VSR instance.

Configuring Other Package Managers

VSR is fully compatible with the npm registry API, making it easy to configure with popular package managers beyond vlt.

npm Configuration

Configure npm to use your VSR instance:

Terminal

$ npm config set registry http://localhost:1337

For scoped packages, you can configure specific registries:

Terminal

$ npm config set @yourscope:registry http://localhost:1337

pnpm Configuration

Set VSR as the default registry for pnpm:

Terminal

$ pnpm config set registry http://localhost:1337

For project-specific configuration, add to .npmrc:

.npmrc

registry=http://localhost:1337

Yarn Configuration

For Yarn v1 (Classic):

Terminal

$ yarn config set registry http://localhost:1337

For Yarn v2+ (Berry), add to .yarnrc.yml:

.yarnrc.yml

npmRegistryServer: 'http://localhost:1337'

bun Configuration

Configure bun to use VSR:

Terminal

$ bun config set registry http://localhost:1337

Or add to bunfig.toml:

bunfig.toml

[install]
registry = "http://localhost:1337"

Authentication

VSR supports standard npm authentication tokens. After configuring your registry, authenticate using:

Terminal

$ npm login --registry=http://localhost:1337

For automated environments, you can use token-based authentication by adding to .npmrc:

.npmrc

//localhost:1337/:_authToken=your-token-here