Manuals / The Buf Schema Registry (BSR) / Automate code generation / Integrate with Remote Packages

NPM

The Buf Schema Registry provides remote packages for JavaScript and TypeScript: consume generated SDKs from modules and plugins using dependency management tools like NPM and Yarn.

This provides consumers of your API with generated SDKs on demand. With generated SDKs, you no longer need to generate code from Protobuf locally, and thus no longer need for consumers to pull in Protobuf files or perform any generation whatsoever.

Setup

JavaScript and TypeScript source code generated by the BSR is hosted on the BSR's NPM registry at:

buf.build/gen/npm/v1

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/* packages 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 NPM packages 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 package names:

Package name syntax

npm install @buf/{moduleOwner}_{moduleName}.{pluginOwner}_{pluginName}

Examplenpm install @buf/bufbuild_eliza.bufbuild_connect-es

Legend:

constant{variable}

In this example, @buf/bufbuild_eliza.bufbuild_connect-es, the BSR generates code for the bufbuild/eliza module using the bufbuild/connect-es plugin.

Installing packages

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

$ npm install @buf/bufbuild_eliza.bufbuild_connect-es

Slow installation?

You may notice that installing packages from the BSR npm registry using npm install can take longer than installing from the standard npm registry. This happens because packages are generated "on the fly"—that is, they're lazily generated and then cached. The first npm install typically takes longer than subsequent requests.

You can use any plugin that generates JavaScript/TypeScript, which can simplify Protobuf workflows down to two steps:

buf push your module to the BSR
npm install your generated NPM package

Versions

By default, when you npm install a Buf module, the BSR generates code from the most recent reference for the module. But you can also install a specific package version using npm's standard @ syntax referencing an explicit version or a draft name.

$ npm install @buf/bufbuild_eliza.bufbuild_connect-es

Latest

If you do not specify a version, npm will fetch @latest by default, which resolves to the package version syntax described below.

$ npm install @buf/bufbuild_eliza.bufbuild_connect-es@latest

Draft

The BSR supports draft commits. This feature enables you to push unreleased Protobuf file changes and consume generated code without affecting the main branch.

$ buf push --draft dev-draft
$ npm install @buf/bufbuild_eliza.bufbuild_connect-es@dev-draft

The package version for drafts will contain a zero-based timestamp so you can easily differentiate between your main branch versus those that originate from a draft.

0.2.1-00000000000000-9bb41b97ede9.3

Caveats

Drafts with names that could be interpreted as valid semver ranges or names that contain / are not compatible with the NPM registry versioning scheme.

Full Syntax

NPM version syntax

{pluginVersion}-{moduleTimestamp}-{moduleCommit}.{pluginRevision}

Example0.2.1-20220706172350-dbde79169a01.3

Legend:

{variable}

With package versions (valid semver):

The version core is the plugin version 0.2.1
The semver pre-release version is composed of:
module commit timestamp (YYYYMMDDHHMMSS) 20220706172350
module commit short name (12 characters) dbde79169a01
The final identifier is the plugin revision 3 for the plugin version

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

$ npm install @buf/bufbuild_eliza.bufbuild_connect-es@0.8.3-20221224180530-f3801d450ef9.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 are not 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 and 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!