Sign inSign up
Buf Schema Registry / Generated SDKs
/

Using generated SDKs – Tutorial

Generated SDKs are created by the Buf Schema Registry (BSR) and contain code generated from Protobuf schemas and plugins. They can be installed as dependencies using popular package managers like NPM, Go, Maven/Gradle, and Swift Package Manager, enabling you to easily consume Protobuf APIs without manually generating code or interacting with the schemas directly. For example, mobile or web teams that do not directly own Protobuf schemas can use generated SDKs to consume Protobuf APIs from other teams.

Prerequisites

Key concepts

module
A module is a collection of Protobuf files that are configured, built, and versioned as a logical unit. Modules are the basic unit of organization for all Buf operations.
plugins
Plugins are external programs that enable the transformation of Protobuf schemas into other constructs. They're used in this context to generate the client code that is packaged into the generated SDKs.
repository
A repository is the remote representation of a module within the BSR. Each generated SDK is created from the Protobuf code in a repository and the plugins you choose.

1. Find generated SDKs

Usually, you'll have a direct URL for the repository you want to use, either from the API owner or from your internal documentation. You can also search for a repository if you know its name, or browse what's available to you:

  1. Go to your dashboard and click Organizations in the left nav to see all of the organizations you belong to:

    Screen shot of left nav with Organizations selected

  2. Click on an organization to view all of its repositories, then click on the repository you want to use.

  3. Click the SDKs tab to see the generated SDKs for this repository:

    Screen shot of top nav with SDKs tab selected

For this tutorial, you can skip the above steps and go directly to the SDKs tab of the eliza repository in the connectrpc organization.

2. Choose language, plugins, and package manager

You have control over what's included in your SDK—you can choose the repository (which you've already done) and then choose the language, plugins, package manager, and the branch or tag of the repository itself. This enables you to key development to a specific version of the schema. Once you choose the language, the BSR will default to that language in the future unless you change it.

You can include multiple plugins by clicking on more than one to select them, but for this tutorial, you'll just use one.

  1. Once you're in the module's SDKs tab, the BSR presents a language picker. Click JavaScript.

    Screen shot of language picker

  2. A gallery of JavaScript-compatible plugins appears. Click connectrpc/es to choose the connectrpc_es plugin.

    Screen shot of plugin picker

  3. Click Continue. A panel with the available package managers and installation instructions appears. You can choose a different manager than the default, but we'll stick with NPM.

3. Setup and installation

The Package Manager section allows you to choose between different managers, and provides a one-time configuration. The Available SDKs panel beneath it provides the installation instructions for the SDKs generated from the repository and each plugin you selected:

Screen shot of package manager panel
  1. Run the configuration command, then either click the One-time registry configuration check box or click Completed.
  2. Follow the provided installation instructions to install the SDK. You can now use the SDK, and can see a link to integration instructions.

4. Changing the branch or tag

The BSR defaults to providing SDKs at the latest module and plugin version unless otherwise specified. To pin SDKs to a specific repository version, select the Current reference dropdown near the top of the SDKs tab and choose a branch or tag:

Screen shot of package manager panel

You can reset the module to latest by going back to the Current reference dropdown and choosing Reset current reference. To specify a specific plugin version to generate SDKs with, select the Plugin version dropdown for a given SDK under the Available SDKs section and choose a plugin version:

Screen shot of package manager panel

Notice that when you make these changes, the installation command updates to reflect the new version (this result is from choosing the demo tag):

npm install @buf/connectrpc_eliza.connectrpc_es@1.0.0-20230913231627-233fca715f49.1

This syntax identifies the plugin version first, and then the exact commit in the repository that the demo tag represents. For more information on the specifics of the syntax, see the NPM guide. The guides for the other dependency managers have similar sections.

  1. Prerequisites
  2. Key concepts
  3. 1. Find generated SDKs
  4. 2. Choose language, plugins, and package manager
  5. 3. Setup and installation
  6. 4. Changing the branch or tag
  7. Related docs