Buf Schema Registry (BSR)

NPM

The Buf Schema Registry provides generated SDKs for JavaScript-based languages in the form of an NPM registry, just like any other JavaScript library. It generates SDKs automatically when you push schema changes, which eliminates the need to manage a Protobuf toolchain or generate code locally.

The BSR's NPM registry is hosted at buf.build/gen/npm/v1. See the tutorial for instructions on how to access generated SDKs from the BSR directly.

Setup

NPM is configured to use the public NPM registry at registry.npmjs.org by default. To configure NPM to use Buf's NPM registry for the @buf package scope, use this command to set your NPM config:

$ npm config set @buf:registry https://buf.build/gen/npm/v1

This updates your global .npmrc to fetch @buf/* SDKs from the BSR. You can configure Yarn in an analogous way:

$ yarn config set @buf:registry https://buf.build/gen/npm/v1

Using private packages

To install SDKs generated from private Buf modules, you need to configure NPM to send an authentication token with each request to the BSR NPM registry:

$ npm config set //buf.build/gen/npm/v1/:_authToken {token}

This command will add an entry to your .npmrc file:

.npmrc token syntax
//buf.build/gen/npm/v1/:_authToken={token}
Example//buf.build/gen/npm/v1/:_authToken=84612b6cbe8f4...
Legend:
constant{variable}

You can use an existing auth token or generate a new one. To create a new one, log into the BSR, navigate to your user settings page, and click Create Token.

Using the NPM registry

The BSR NPM registry has a special syntax for SDK names:

Package name syntax
Examplenpm install @buf/connectrpc_eliza.connectrpc_es
Legend:
constant{variable}

In this example, @buf/connectrpc_eliza.connectrpc_es, the BSR generates code for the connectrpc/eliza module using the connectrpc/es plugin.

Installing SDKs

With your NPM config set, you can install @buf/* SDKs in any standard NPM project. Here's an example installation command:

$ npm install @buf/connectrpc_eliza.connectrpc_es
Slow installation?

You may notice that installing SDKs from the BSR NPM registry using npm install can take longer than installing from the standard NPM registry. This happens because they're lazily generated and then cached. The first npm install typically takes longer than subsequent requests because of this.

Versions

By default, when you npm install a Buf module, the BSR generates code from the most recent reference for the module. However, you can also install a specific SDK version using NPM's standard @ syntax, referencing an explicit version or a draft name. To discover SDK versions, you can browse a repository's SDK page, which has installation instructions and an interactive UI.

The basic install command is:

$ npm install @buf/connectrpc_eliza.connectrpc_es

Latest

If you don't specify a version, NPM will fetch @latest by default, but you can also specify it:

$ npm install @buf/connectrpc_eliza.connectrpc_es@latest

Commit

This uses the commit- prefix to indicate that a commit is being referenced.

To get the generated SDK for the module at a commit:

$ npm install @buf/connectrpc_eliza.connectrpc_es@commit-8b8b971d6fde4dc8ba5d96f9fda7d53c

Tag

This uses the tag- prefix to indicate that a tag is being referenced.

To get the generated SDK for the module at a tag:

$ npm install @buf/connectrpc_eliza.connectrpc_es@tag-demo

Branches

The BSR supports commits on branches. This feature enables you to push unreleased Protobuf file changes and consume generated code without affecting the main branch. This uses the branch- prefix to indicate that a branch is being referenced.

To get the generated SDK for the module from a branch:

$ npm install @buf/connectrpc_eliza.connectrpc_es@branch-dev

For commits on branches, the commit timestamp component of the version is always zeroed out to easily differentiate SDK versions using commits on branches that aren't main:

0.13.1-00000000000000-8b8b971d6fde.1
Caveats

Branches with names that contain / aren't compatible with the NPM registry versioning scheme.

Full syntax

NPM version syntax
{pluginVersion}-{moduleTimestamp}-{moduleCommit}.{pluginRevision}
Example0.13.1-20230822171018-8b8b971d6fde.1
Legend:
{variable}

With SDK versions (valid semver):

  • The version core is the plugin version 0.13.1
  • The semver pre-release version is composed of:
    • module commit timestamp (YYYYMMDDHHMMSS) 20230822171018
    • module commit short name (12 characters) 8b8b971d6fde
  • The final identifier is the plugin revision 1 for the plugin version

Most users will likely use @latest, but if you need to reference an SDK version explicitly, you can do so like this:

$ npm install @buf/connectrpc_eliza.connectrpc_es@0.13.1-20230822171018-8b8b971d6fde.1

Other package managers

Because the BSR NPM registry implements NPM's public registry API, you should be able to use it with package management tools outside of NPM, such as Yarn and pnpm, though with some known limitations:

Please be aware that Yarn versions greater than v1.10.0 and less than v2 aren't supported. These versions of Yarn require the shasum field in the dist object to be set, but the BSR can't compute a digest without generating the code for all possible versions of the package.

Available plugins

For a full list of supported plugins, navigate to the BSR plugins page and search for JavaScript or TypeScript.

To learn more about how these plugins are packaged and distributed check out the bufbuild/plugins repository. If you find a useful plugin that should be added please file an issue!