Skip to content

Latest commit

 

History

History
75 lines (51 loc) · 5.25 KB

proto.md

File metadata and controls

75 lines (51 loc) · 5.25 KB

Protocol Buffers and gRPC (UNSTABLE)

UNSTABLE API: contents of this page are not subject to our usual semver guarantees. We may make breaking changes in any release. Please try this API and provide feedback. We intend to promote it to a stable API in a minor release, possibly as soon as v2.1.0.

ts_proto_library uses the Connect library from bufbuild, and supports both Web and Node.js:

This Bazel integration follows the "Local Generation" mechanism described at https://connectrpc.com/docs/web/generating-code#local-generation, using packages such as @bufbuild/protoc-gen-es, @connectrpc/protoc-gen-connect-query, and @connectrpc/protoc-gen-connect-es as plugins to protoc.

The aspect configure command auto-generates ts_proto_library rules as of the 5.7.2 release. It's also possible to compile this library into your Gazelle binary.

Note: this API surface is not included in defs.bzl to avoid eager loads of rules_proto for all rules_ts users.

Installation

If you install rules_ts in WORKSPACE, you'll need to install the deps of rules_proto, like this:

load("@rules_proto//proto:repositories.bzl", "rules_proto_dependencies")

rules_proto_dependencies()

If you use bzlmod/MODULE.bazel then no extra install is required.

Future work

  • Allow users to choose other plugins. We intend to wait until http://github.com/bazelbuild/rules_proto supports protoc plugins.
  • Allow users to control the output format. Currently it is hard-coded to js+dts, and the JS output uses ES Modules.

ts_proto_library

load("@aspect_rules_ts//ts:proto.bzl", "ts_proto_library")

ts_proto_library(name, node_modules, proto, protoc_gen_options, gen_connect_es, gen_connect_query,
                 gen_connect_query_service_mapping, copy_files, proto_srcs, files_to_copy, kwargs)

A macro to generate JavaScript code and TypeScript typings from .proto files.

PARAMETERS

Name Description Default Value
name name of resulting ts_proto_library target none
node_modules Label pointing to the linked node_modules target where @bufbuild/protoc-gen-es is linked, e.g. //:node_modules. Since the generated code depends on @bufbuild/protobuf, this package must also be linked. If gen_connect_es = True then @bufbuild/proto-gen-connect-es should be linked as well. If gen_connect_query = True then @bufbuild/proto-gen-connect-query should be linked as well. none
proto the proto_library target that contains the .proto files to generate code for. none
protoc_gen_options dict of protoc_gen_es options. See https://github.com/bufbuild/protobuf-es/tree/main/packages/protoc-gen-es#plugin-options {}
gen_connect_es whether protoc_gen_connect_es should generate grpc services, and therefore *_connect.{js,d.ts} should be written. True
gen_connect_query whether protoc_gen_connect_query should generate TanStack Query clients, and therefore *_connectquery.{js,d.ts} should be written. False
gen_connect_query_service_mapping mapping from source proto file to the named RPC services that file contains. Needed to predict which files will be generated by gen_connect_query. See https://github.com/connectrpc/connect-query-es/tree/main/examples/react/basic/src/gen

For example, given a.proto which contains a service Foo and b.proto that contains a service Bar, the mapping would be {"a.proto": ["Foo"], "b.proto": ["Bar"]}		 {}
copy_files whether to copy the resulting .d.ts files back to the source tree, for the editor to locate them. True
proto_srcs the .proto files that are being generated. Repeats the srcs of the proto_library target. This is used only to determine a default for files_to_copy. None
files_to_copy which files from the protoc output to copy. By default, performs a replacement on proto_srcs with the typical output filenames. None
kwargs additional named arguments to the ts_proto_library rule none