DEV Community

Alex Spinov
Alex Spinov

Posted on

Buf Has a Free API: Make Protocol Buffers Actually Developer-Friendly

#api #protobuf #grpc #go

Protobuf is powerful but painful. protoc plugins, code generation configs, import path hell — Buf fixes all of it.

What Is Buf?

Buf is a suite of tools for Protocol Buffers and gRPC: linting, breaking change detection, code generation, and a schema registry. Think ESLint + npm for protobuf.

# Install
npm install -g @bufbuild/buf

# Initialize
buf config init

# Lint your .proto files
buf lint

# Generate code
buf generate

# Check for breaking changes
buf breaking --against .git#branch=main
Enter fullscreen mode Exit fullscreen mode

Linting 

# buf.yaml
version: v2
lint:
  use:
    - STANDARD
  except:
    - FIELD_LOWER_SNAKE_CASE
Enter fullscreen mode Exit fullscreen mode 
$ buf lint
pet/v1/pet.proto:10:3: Field name "petName" should be lower_snake_case
pet/v1/pet.proto:14:1: Service "petService" should be PascalCase
Enter fullscreen mode Exit fullscreen mode

Catch naming issues, import problems, and style violations before they reach code review.

Breaking Change Detection 

$ buf breaking --against .git#branch=main
pet/v1/pet.proto:8:3: Field "1" on message "Pet" changed type from "string" to "int32".
pet/v1/pet.proto:12:3: Field "3" with name "owner" on message "Pet" was deleted.
Enter fullscreen mode Exit fullscreen mode

Accidentally changed a field type? Deleted a field? Buf catches it before you break clients.

Code Generation 

# buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go
    out: gen/go
  - remote: buf.build/connectrpc/go
    out: gen/go
  - remote: buf.build/bufbuild/es
    out: gen/ts
Enter fullscreen mode Exit fullscreen mode 
buf generate  # Generates Go + TypeScript from .proto files
Enter fullscreen mode Exit fullscreen mode

No protoc plugin installation. No local binary management. Remote plugins run in Buf's cloud.

BSR (Buf Schema Registry) 

# Push schemas to registry
buf push

# Use schemas from registry (like npm packages)
buf.build/googleapis/googleapis
buf.build/grpc/grpc
Enter fullscreen mode Exit fullscreen mode

Why Buf

  • Linting — catch protobuf anti-patterns
  • Breaking detection — prevent API breaks
  • Remote plugins — no protoc plugin hell
  • Schema registry — share .proto files like npm packages
  • Connect-RPC — their modern gRPC alternative works in browsers

Building API infrastructure? Check out my developer tools or email spinov001@gmail.com.

Top comments (0)