close
Skip to content

Generate code with remote plugins#

A remote plugin is a hosted Protobuf plugin on the BSR. buf generate sends an input to the BSR’s plugin executor, the BSR runs each plugin against that input, and the output is unpacked to your local file system.

This page covers configuring remote plugins in buf.gen.yaml and the plugin combinations that need coordination.

Before you start#

Configure remote plugins in buf.gen.yaml#

Pick the language tab for the plugins you want to invoke. Each remote: reference can pin a plugin version (:v1.36.11) for reproducible builds; pin in CI and any examples you commit.

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    out: gen/go
    opt: paths=source_relative
buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/java
    out: gen/java
  - remote: buf.build/grpc/java
    out: gen/java
buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/bufbuild/es
    out: gen/js
buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/python
    out: gen/python
  - remote: buf.build/grpc/python
    out: gen/python
buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/ruby
    out: gen/ruby
  - remote: buf.build/grpc/ruby
    out: gen/ruby
buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/apple/swift
    opt: Visibility=Public
    out: gen/swift
  - remote: buf.build/connectrpc/swift
    opt: Visibility=Public
    out: gen/swift

To browse other plugins, see the BSR plugins page.

Run buf generate#

From the workspace root:

$ buf generate

buf generate sends the resolved input to the BSR’s plugin executor, invokes each plugin from buf.gen.yaml against it, and writes the responses to disk under each plugin’s out: directory.

By default the command looks for buf.gen.yaml in the current directory; pass --template to point it elsewhere:

$ buf generate --template templates/buf.go.gen.yaml

For a Go workspace using the example above, the output tree looks like:

workspace_root
├── buf.gen.yaml
└── gen
    └── go
        └── pet
            └── v1
                ├── pet.pb.go
                └── pet_grpc.pb.go

Other languages produce equivalent trees under their own out: directories.

Mix local and remote plugins#

buf.gen.yaml accepts both remote: and local: plugin entries in the same file. Plugins run in parallel; their outputs are written to disk in the order they appear in plugins:.

Common combinations#

Most plugins on the BSR can be invoked on their own; the entries below are the ones whose typical use requires another plugin or a runtime library.

Connect-Go and protoc-gen-go#

Connect-Go generates Go service clients and handlers that work over gRPC, gRPC-Web, and Connect. The Connect-Go plugin generates service stubs only and depends on the message types produced by protoc-gen-go, so both plugins have to run together:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/connectrpc/go:v1.18.1
    out: gen/go
    opt: paths=source_relative

Connect-ES#

Connect-ES brings Connect to TypeScript, browsers, and Node.js. The bufbuild/es plugin generates both message types and Connect service stubs in one pass:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/bufbuild/es
    out: gen/es

The generated code uses the @connectrpc/connect and @bufbuild/protobuf runtime libraries, installed as ordinary npm dependencies. For end-to-end usage, see the Connect-ES quickstarts for web and Node.js.

Connect-Swift and apple/swift#

Connect-Swift generates Swift clients for the gRPC-Web and Connect protocols. The Connect-Swift plugin emits service stubs only; message types come from apple/swift, so both plugins run together:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/apple/swift
    opt: Visibility=Public
    out: gen/swift
  - remote: buf.build/connectrpc/swift
    opt: Visibility=Public
    out: gen/swift

grpc-go and protoc-gen-go#

grpc-go generates Go service stubs for gRPC. Like Connect-Go, the grpc-go plugin generates service stubs only and depends on the message types from protoc-gen-go:

buf.gen.yaml
version: v2
plugins:
  - remote: buf.build/protocolbuffers/go:v1.36.11
    out: gen/go
    opt: paths=source_relative
  - remote: buf.build/grpc/go:v1.5.1
    out: gen/go
    opt: paths=source_relative

For new Go services, Connect-Go is Buf’s preferred path; grpc-go is the right choice when an existing gRPC ecosystem (interceptors, server tooling) is in play.

Next steps#