use-buf

Use Buf

Use the Buf CLI as the source of truth for Protobuf compilation, dependency resolution, linting, breaking-change detection, and code generation.

Inspect Before Changing

1. Read repository instructions.
2. Search the repository root and likely API directories for buf.yaml, buf.lock, buf.gen.yaml, and buf.gen.<domain>.yaml files.
3. Inspect the configuration version, module paths, dependency declarations, lint policy, breaking policy, inputs, plugin pins, output paths, and existing generation scripts.
4. Run buf --version and check repository/CI tool pins before using features from a newer configuration schema.
5. Diagnose configuration or dependency problems before changing .proto files to work around them.

Use one default buf.gen.yaml. Introduce buf.gen.<domain>.yaml only when generation products genuinely require isolated plugin sets, inputs, or outputs. Pass non-default templates explicitly with buf generate --template <file>.

Keep Configuration Responsibilities Clear

• Use buf.yaml for workspaces/modules, BSR dependencies, lint rules, breaking rules, policies, and Buf check plugins.
• Use buf.gen.yaml or buf.gen.<domain>.yaml for protoc-gen-* code-generation plugins, inputs, output directories, options, and managed mode.
• Use buf.lock as generated dependency resolution state. Do not edit it manually.
• Keep configuration in the repository root or the established API workspace directory unless repository structure requires otherwise.

Read references/configuration.md before adding modules, dependencies, check plugins, generation templates, or output paths.

Manage Dependencies Deliberately

• Prefer BSR modules for maintained dependencies, including Google APIs, well-known types, Protovalidate, and grpc-gateway annotations.
• Add or remove dependencies in buf.yaml, then run buf dep update and inspect the buf.lock diff.
• Use buf dep graph --format json to identify the resolved dependency chain.
• Use buf dep prune only after confirming an import is genuinely unused.
• When a type appears missing, inspect configuration and the lockfile, run buf dep update, then run buf build or buf generate to obtain the compiler's concrete import/type error.
• Never hardcode an operating system's Buf cache location. Export the pinned module with buf export when source inspection is required.