> ## Documentation Index
> Fetch the complete documentation index at: https://site.aspect.build/llms.txt
> Use this file to discover all available pages before exploring further.

# @aspect_rules_ts//ts:proto.bzl

> Bazel rules_ts unstable Protobuf and gRPC support: ts_proto_library rule using bufbuild Connect to generate TypeScript code for Web and Node.js.

<Callout icon="book">
  Documentation for [@aspect\_rules\_ts@v3.8.4](https://registry.bazel.build/modules/aspect_rules_ts/3.8.4) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_ts/blob/v3.8.4/ts/proto.bzl)
</Callout>

# 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:

* [https://connectrpc.com/docs/web/getting-started](https://connectrpc.com/docs/web/getting-started)
* [https://connectrpc.com/docs/node/getting-started](https://connectrpc.com/docs/node/getting-started)

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

The [aspect configure](https://docs.aspect.build/cli/commands/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](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.

## Function: `ts_proto_library`

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

### Parameters

<ParamField body="name" type="unknown" required>
  name of resulting ts\_proto\_library target
</ParamField>

<ParamField body="node_modules" type="unknown" required>
  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.
</ParamField>

<ParamField body="proto" type="unknown" required>
  the `proto_library` target that contains the .proto files to generate code for.
</ParamField>

<ParamField body="protoc_gen_options" type="unknown" default={`{}`}>
  dict of protoc\_gen\_es options.
  See [https://github.com/bufbuild/protobuf-es/tree/main/packages/protoc-gen-es#plugin-options](https://github.com/bufbuild/protobuf-es/tree/main/packages/protoc-gen-es#plugin-options)
</ParamField>

<ParamField body="gen_connect_es" type="unknown" default={`False`}>
  \[deprecated] whether protoc\_gen\_connect\_es should generate grpc services, and therefore `*_connect.{js,d.ts}` should be written.
</ParamField>

<ParamField body="gen_connect_query" type="unknown" default={`False`}>
  whether protoc\_gen\_connect\_query should generate [TanStack Query](https://tanstack.com/query) clients, and therefore `*_connectquery.{js,d.ts}` should be written.
</ParamField>

<ParamField body="gen_connect_query_service_mapping" type="unknown" default={`{}`}>
  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](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"]}`
</ParamField>

<ParamField body="copy_files" type="unknown" default={`True`}>
  whether to copy the resulting `.d.ts` files back to the source tree, for the editor to locate them.
</ParamField>

<ParamField body="proto_srcs" type="unknown" default={`None`}>
  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`.
</ParamField>

<ParamField body="files_to_copy" type="unknown" default={`None`}>
  which files from the protoc output to copy. By default, performs a replacement on `proto_srcs` with the typical output filenames.
</ParamField>

<ParamField body="kwargs" type="unknown">
  additional named arguments to the ts\_proto\_library rule
</ParamField>