Buf Schema Registry (BSR)

Buf Schema Registry FAQs

Can I depend on modules from the BSR and use the Buf CLI when offline?

Yes. Buf caches your dependencies locally when you run commands that use them (such as buf build, buf lint, and buf breaking) while connected to the Internet. By default, your cache lives at ~/.cache/buf on Mac or Linux, and %LocalAppData%\buf on Windows. All commands that use module dependencies will continue to work once your cache is initially populated.

Can I use remote plugins when offline?

No. protoc plugins are built and executed in a number of ways across the Protobuf ecosystem: compiled executables (statically or dynamically linked), JVM JAR files, files run with NPM, and so on. We use Docker to package protoc plugins and make them available for universal use, and this ability to specify a single value in your buf.gen.yaml file without needing to know how the plugin is developed is a key reason remote plugins are so valuable.

However, we don't think it's a good idea for the Buf CLI to require you to have a working Docker installation locally—it would negate much of the universal benefit of Buf itself. So, we engineered remote plugins to run on our servers. We copy your .proto files to the BSR, then run a Docker container there to execute the plugin and send back the generated code. This means that remote plugins require you to be connected to the BSR.

We've started working on a WASM-based protoc plugin ecosystem that would solve this issue, where we'd provide you with a WASM binary that you'd download and execute locally. This is the best future we can see for offline use. However, WASM is still in relative infancy, and we want to get more buy-in across the Protobuf community before enabling a WASM-based plugin ecosystem more widely.

Does a deps value in my buf.yaml file have to be a reference to a BSR module?

Yes. The value must be a valid path to a BSR module (either the public BSR at buf.build or a private BSR instance). It can't be a local Git reference to a buf.yaml file or a URL path to a Git repo. This means that if you have a module that you'd like to use as a dependency, it must also be pushed to the BSR.

Where can I find available options for a plugin on the BSR?

On the left-hand sidebar of the plugin page, there's a link to the plugin's GitHub repository, where details like plugin options, tutorials, and documentation should be available:

Screenshot of 'About' section of plugin page

If you're using a plugin as part of a generated SDK for one of your modules, the SDKs tab of your module also has a link to the integration guide for the plugin:

Screenshot of integation guide link

How do I document my Protobuf schema?

Protobuf supports comments, and we encourage you to document your Protobuf types and services like you document other code. The BSR auto-generates documentation for your Protobuf schema.

How do I delete a branch?

You can't. The BSR is not just a VCS, but also a package registry (because of generated SDKs), so deleting a branch can have side effects that are much more impactful than branch deletion in Git.

Generating code

How can I modify the output of generated SDKs and/or change the plugin options?

There is currently no way to modify the generated SDK output directly. We have an opinionated set of plugin options (usually the defaults) which determine the output. Your choices are:

Why does generating Java code using my valid module as an input result in an error?

Some users' Protobuf packages may use Java reserved keywords (public, native, etc.). The generated code will fail to compile if it includes one of these keywords, regardless of whether it is generated by a plugin locally or remotely. We suggest avoiding the use of Java reserved keywords in modules that you expect to use for generating code.

Can Maven JARs be hosted without the build.buf.gen prefix?

No. The package name prefix is tied to the host name of the BSR, so it can't be changed or removed. Private BSR instances for Pro, Enterprise, and On-prem plans have a different prefix based on their host name, however.

When I run buf generate, my Go code has incorrect imports for dependencies. How do I fix this?

This is often due to the use of managed mode, which overwrites Go import paths using the configuration in buf.gen.yaml. If you don't want to use the managed configuration for some dependencies, you must add an except entry in buf.gen.yaml under the managed.go_package_prefix stanza.

When I use a generated Go SDK, the Go code is using the wrong import for dependencies. How do I fix this?

Use of generated SDKs requires that all of the module's imports also use generated SDKs. This cannot be changed or configured. If you really need your module to import Go code from some other Go import path, you need to generate your own SDKs with relevant configuration.

Is there any way to configure the go_package behavior for Go generated SDKs?

No. The go_package option is automatically set to match the module name and package path so that you don't need to set it at all.