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 Cargo, Go, Gradle, Maven, NPM, pip 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

Create a Buf account, if you haven't already
Sign in to the BSR

Key concepts

module: A module is the key primitive in the Buf ecosystem, and represents a collection of Protobuf files that are configured, built, and versioned as a logical unit.
workspace: Workspaces are collections of modules that are defined together in the same buf.yaml file to create a local working environment. All modules in a workspace can import each other without specific dependency declarations, and can also share any dependencies that are defined for the workspace. Workspaces are the default input for Buf CLI commands.
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 Buf Schema Registry (BSR) repository is a remote location representing a module's commits, labels, and label histories. Repositories are the basis of all of the BSR's features and shareable artifacts.

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:

Go to your dashboard, click on your username, and click Organizations to see all of the organizations you belong to:
Click on an organization to view all of its repositories, then click on the repository you want to use.
Click the SDKs tab to see the generated SDKs for this repository:

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 label 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.

Once you're in the module's SDKs tab, the BSR presents a language picker. Click JavaScript.
A gallery of JavaScript-compatible plugins appears. Click connectrpc/es to choose the connectrpc_es plugin.
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:

Run the configuration command, then either click the One-time registry configuration check box or click Completed.
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 label

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 commit or label:

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

$ 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 label represents. For more information on the specifics of the syntax, see the NPM guide. The guides for the other dependency managers have similar sections.

Read the generated SDKs overview
View the manual installation guides for more detail: