DEV Community

Alex Spinov
Alex Spinov

Posted on

Buf Has Free Protocol Buffer Tooling — Here's Why Teams Are Ditching protoc

#grpc #api #devops #webdev

protoc is painful. Buf replaces it with a modern, fast, and developer-friendly Protocol Buffer toolchain.

What is Buf?

Buf is a complete toolchain for Protocol Buffers: linting, breaking change detection, code generation, and a registry — all in one CLI.

Quick Start 

# Install
brew install bufbuild/buf/buf

# Initialize a project
buf config init
Enter fullscreen mode Exit fullscreen mode

Project Structure 

proto/
  buf.yaml          # Buf configuration
  buf.gen.yaml      # Code generation config
  user/
    v1/
      user.proto
  order/
    v1/
      order.proto
Enter fullscreen mode Exit fullscreen mode

buf.yaml 

version: v2
modules:
  - path: proto
lint:
  use:
    - STANDARD
breaking:
  use:
    - FILE
Enter fullscreen mode Exit fullscreen mode

buf.gen.yaml 

version: v2
plugins:
  - local: protoc-gen-es
    out: src/gen
    opt: target=ts
  - local: protoc-gen-connect-es
    out: src/gen
    opt: target=ts
Enter fullscreen mode Exit fullscreen mode

Key Commands 

# Lint your proto files
buf lint

# Check for breaking changes
buf breaking --against .git#branch=main

# Generate code
buf generate

# Format proto files
buf format -w
Enter fullscreen mode Exit fullscreen mode

Linting (Catch Mistakes Early) 

$ buf lint
proto/user/v1/user.proto:5:1: Field name "userId" should be lower_snake_case
proto/user/v1/user.proto:12:1: RPC request type "Get" should be suffixed with "Request"
proto/user/v1/user.proto:13:1: Package name should have a version suffix (e.g., "user.v1")
Enter fullscreen mode Exit fullscreen mode

Breaking Change Detection 

$ buf breaking --against .git#branch=main
proto/user/v1/user.proto:8:3: Field "3" on message "User" changed type from "string" to "int32".
proto/order/v1/order.proto:5:1: Previously present field "2" with name "amount" on message "Order" was deleted.
Enter fullscreen mode Exit fullscreen mode

This prevents you from shipping breaking API changes to production.

Buf vs protoc

Feature Buf protoc
Setup brew install buf Download binary + plugins
Linting Built-in None
Breaking Changes Built-in None
Formatting Built-in None
Dependency Mgmt buf.lock Manual
Speed Fast (Go) Slow (C++)
Config YAML CLI flags

Buf Schema Registry (BSR) 

# Push your module
buf push

# Use modules from BSR
Enter fullscreen mode Exit fullscreen mode 
# buf.yaml
version: v2
deps:
  - buf.build/googleapis/googleapis
  - buf.build/grpc-ecosystem/grpc-gateway
Enter fullscreen mode Exit fullscreen mode

CI/CD Integration 

# GitHub Actions
- uses: bufbuild/buf-setup-action@v1
- uses: bufbuild/buf-lint-action@v1
- uses: bufbuild/buf-breaking-action@v1
  with:
    against: "https://github.com/your-org/your-repo.git#branch=main"
Enter fullscreen mode Exit fullscreen mode

Need structured API data? Check out my web scraping actors on Apify Store — clean data from any API. For custom solutions, email spinov001@gmail.com.

Top comments (0)