Skip to content

npm#

The BSR exposes an npm registry at https://buf.build/gen/npm/v1 and serves BSR-generated JavaScript and TypeScript SDKs under the @buf scope. A first install:

$ npm install @buf/connectrpc_eliza.bufbuild_es

For an end-to-end walkthrough, see the generated SDKs quickstart.

Configure npm#

npm uses registry.npmjs.org by default. Point the @buf scope at the BSR registry via npm config:

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

This writes an entry to your global .npmrc so every @buf/* install resolves through the BSR.

For Yarn Classic (1.x), the same .npmrc works. For Yarn Berry (2.x and later), configure the scope through Yarn’s own config instead:

$ yarn config set npmScopes.buf.npmRegistryServer https://buf.build/gen/npm/v1/

Authenticate for private modules#

To install SDKs generated from private modules, configure npm to send a BSR token with each request to the BSR npm registry:

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

That writes a token line into .npmrc:

.npmrc
//buf.build/gen/npm/v1/:_authToken=84612b6cbe8f4...

For self-hosted or dedicated BSR instances, swap buf.build for your instance host:

.npmrc (private BSR instance)
//your-bsr-instance.example.com/gen/npm/v1/:_authToken=84612b6cbe8f4...

Use an existing token or create a new one.

Install an SDK#

Each BSR-generated npm package is named after the module and plugin that produced it:

Package name format
@buf/{moduleOwner}_{moduleName}.{pluginOwner}_{pluginName}

For example, @buf/connectrpc_eliza.bufbuild_es is the connectrpc/eliza module produced by the bufbuild/es plugin:

$ npm install @buf/connectrpc_eliza.bufbuild_es

The first install of any specific SDK version takes longer than subsequent installs: the BSR generates the package on demand, then caches it.

Pin to a specific version#

npm install accepts the BSR npm package name with any of these references after the @:

Latest commit on the default label
$ npm install @buf/connectrpc_eliza.bufbuild_es
$ npm install @buf/connectrpc_eliza.bufbuild_es@latest
Specific module commit (commit- prefix)
$ npm install @buf/connectrpc_eliza.bufbuild_es@commit-8b8b971d6fde4dc8ba5d96f9fda7d53c
Specific label (label- prefix)
$ npm install @buf/connectrpc_eliza.bufbuild_es@label-demo
Explicit version string
$ npm install @buf/connectrpc_eliza.bufbuild_es@2.2.2-20230913231627-233fca715f49.1

Labels whose names contain / aren’t compatible with the npm version syntax; rename the label or pin by commit instead.

To pin a specific plugin version (rather than the latest plugin against a chosen module ref), use the buf registry sdk version CLI command:

$ buf registry sdk version --module=buf.build/connectrpc/eliza --plugin=buf.build/bufbuild/es

Version string anatomy#

Version syntax
PLUGIN_VERSION-MODULE_TIMESTAMP-COMMIT_ID.PLUGIN_REVISION

# Example
2.2.2-20230913231627-233fca715f49.1
Part Example Source
Version core 2.2.2 Plugin version.
Pre-release: timestamp 20230913231627 Module commit timestamp (YYYYMMDDHHMMSS).
Pre-release: commit 233fca715f49 First 12 characters of the module commit ID.
Build metadata 1 Plugin revision.

Commits pushed to non-default labels carry 00000000000000 as the timestamp, so they sort below released versions.

Other package managers#

The BSR npm registry implements npm’s public registry API, so it works with pnpm and Yarn Berry (2.x and later).

Yarn versions in [1.10.0, 2) aren’t supported: Yarn 1 requires the shasum field in the dist object, and the BSR can’t compute one without pre-generating every possible version of the package. Yarn 2+ and pnpm work end-to-end.

Available plugins#

The full list of supported JavaScript and TypeScript plugins lives on the BSR plugins page; filter for JavaScript or TypeScript. For a default JavaScript/TypeScript plugin to start with, bufbuild/es generates protobuf-es types and pairs with Connect-ES for service clients.

For how plugins are packaged, see the bufbuild/plugins repository; to request a new plugin, file an issue.