Buf Docs

Appearance

What is Buf? ​

Buf builds tooling for Protocol Buffers, the schema language behind gRPC and ConnectRPC. We think schemas are how APIs should be built, and we’ve made the long argument for that elsewhere. On this page, the short version: a schema gives you type checking, code generation in any language, and forward and backward compatibility guarantees that REST/JSON APIs simply don’t get for free.

Two products do the work:

  • Buf CLI, the command-line tool for working with .proto files.
  • Buf Schema Registry (BSR), a hosted registry that stores Protobuf modules, runs plugins against them, and publishes per-language SDKs.

Why Buf ​

Protobuf has been around for two decades, and for most of that time, adopting it outside Google has been rough. protoc is a compiler and little else. Everything around it (style, dependencies, compatibility, distribution, documentation) gets reinvented by every team that picks up Protobuf, usually as a pile of shell scripts that one person on the team maintains until they leave. Buf exists because that’s a terrible way to use a good technology.

Concretely:

  • API design drifts without enforcement. Nobody’s wrong, exactly, but ten teams at the same company end up with ten different naming conventions, ten different ways to handle pagination, and ten different opinions on enum zero values. You don’t notice until you try to consume more than one of them. buf lint ships with a default style guide built from what we’ve seen work at scale, and runs as fast as the compiler does.
  • Dependency management was absent for twenty years. The Protobuf community shared files by copy-paste or Git submodule and called it a day. No registry, no versioning, no resolver. BSR is the npm, cargo, pip, Go-modules equivalent that Protobuf never had: declare a dependency, pin it, fetch it, move on.
  • Backward compatibility is a promise, not a guarantee. Protobuf’s wire format was designed for safe evolution, but nothing in protoc tells you when an edit breaks your existing consumers. You find out in production. buf breaking runs that check in CI and fails the build instead, against whichever level of strictness fits: source-compatible, package-compatible, wire-compatible, or JSON-compatible.
  • Distributing generated code is a whole side project. The two options have been to centralize protoc and ship stubs yourself, or to ship .proto files and ask every consumer to run protoc themselves. Both paths end the same way: a pile of Makefiles and plugin version pinning, maintained by one person. BSR generated SDKs publish stubs to Go modules, PyPI, Maven, npm, NuGet, Cargo, and Swift Package Manager the moment you push. Consumers go get or npm install them like any other library.
  • Everything else is a desert. Mock servers, fuzz inputs, browsable docs, API call tooling: all standard equipment for REST/JSON, all barely-there for Protobuf. buf curl calls gRPC and Connect services with your schema’s types. BSR documentation serves browsable, searchable schema docs with the same quality as language-native registries. Buf Studio is Postman for Protobuf, in a browser.

Buf CLI ​

buf is a single binary that reads a buf.yaml at the root of your project and figures out what to do with the .proto files under it. Compile, lint, detect breaking changes, format, manage dependencies, generate code, call gRPC and Connect endpoints: one tool, one config file. See the CLI overview for the full command list.

Source is github.com/bufbuild/buf, Apache 2.0.

Buf Schema Registry ​

BSR is to Protobuf what crates.io is to Rust and npm is to Node: the place your schemas live so everyone else can consume them. Push a module, and BSR hosts the schema as a versioned dependency, serves generated documentation, runs remote plugins against it on demand, and publishes generated SDKs into Go modules, PyPI, Maven, npm, NuGet, Cargo, and Swift Package Manager. See the BSR overview for the full feature list.

Next steps ​