protoc-gen-extend

protoc-gen-extend

A protoc plugin that lets you extend generated protobuf types with custom Go code using sidecar files — no type aliasing or wrapper structs required.

The Problem

In Go, you can't add methods to types defined in other packages. If protoc-gen-go generates a User struct in userpb, you're stuck with workarounds like:

// Type definition just to add behavior
type User userpb.User

func (u *User) FullName() string {
    return u.FirstName + " " + u.LastName
}

This breaks type compatibility and requires casts everywhere the original type is used.

The Solution

Write a sidecar .proto.ext.go file next to your .proto file:

proto/
  user.proto
  user.proto.ext.go    ← your extensions
gen/
  userpb/
    user.pb.go         ← generated by protoc-gen-go
    user_ext.pb.go     ← generated by protoc-gen-extend

The sidecar is a plain Go file (with a //go:build ignore tag so go build skips it in place):

//go:build ignore

package userpb

import "strings"

func (m *User) FullName() string {
    return strings.TrimSpace(m.FirstName + " " + m.LastName)
}

func NewUser(first, last string) *User {
    return &User{FirstName: first, LastName: last}
}

protoc-gen-extend picks up the sidecar, validates that all receiver types are messages in the proto file, and emits the code into the generated output package. Methods, constants, constructors, and variables land directly alongside the generated types.

Usage: standalone (recommended)

No install, no PATH setup — go run resolves, caches, and pins the version inline:

go run github.com/codenaugh/protoc-gen-extend@latest generate \
  -sidecar_root proto \
  -out gen \
  -paths_source_relative

Standalone mode parses the .proto files directly (syntax only — no import resolution needed), so it runs before, after, or parallel to your normal codegen, under any driver (protoc scripts, buf, make). Protos without sidecars are skipped, so it's a fast no-op scan for most of the tree.

generate flags

Usage: as a protoc plugin

go install github.com/codenaugh/protoc-gen-extend@latest

protoc \
  --proto_path=proto \
  --go_out=gen \
  --go_opt=paths=source_relative \
  --extend_out=sidecar_root=proto:gen \
  --extend_opt=paths=source_relative \
  proto/user.proto

Note: protoc discovers plugins via PATH, so the installed binary's directory ($GOBIN or $GOPATH/bin) must be on PATH, or pass --plugin=protoc-gen-extend=/path/to/binary explicitly.

Options

Sidecar File Convention

• Named <name>.proto.ext.go to match <name>.proto; tests go in <name>.proto.ext_test.go, emitted as a _test.go file in the generated package (so go test covers the extensions without importing testing into production output)
• Must have a //go:build ignore tag so it's not compiled in place
• Package name is rewritten to match the generated output
• Receiver types are validated against messages in the proto file
• Imports and doc comments are carried through to the generated output
• Supports methods, constants, variables, type declarations, and standalone functions

Validation

If a sidecar references a type that isn't a message in the proto file, the plugin fails with a helpful error:

method Bad has receiver *Foo, but Foo is not a message in user.proto
  available messages: User, Team

Example

See the example/ directory. Run it with:

make example

Development

make build    # build locally
make test     # run tests
make proto    # generate example output
make clean    # remove artifacts