Bazel rules for JavaScript and TypeScript protocol buffers

This library provides rules_js-compatible Bazel rules for generating protocol buffers. The code is experimental and the API has not yet stabilized.

Installation

From the release you wish to use: https://github.com/gonzojive/rules_ts_proto/releases copy the WORKSPACE snippet into your WORKSPACE file.

Usage

load("@rules_proto//proto:defs.bzl", "proto_library")
load("@com_github_gonzojive_rules_ts_proto//ts_proto:defs.bzl", "ts_proto_library")

proto_library(
    name = "greeting_proto",
    srcs = ["greeting.proto"],
    import_prefix = "github.com/gonzojive/rules_ts_proto/example/prefix",
    visibility = ["//visibility:public"],
    deps = [
        "//location:location_proto",
    ],
)

ts_proto_library(
    name = "greeting_ts_proto",
    proto = ":greeting_proto",
    visibility = ["//visibility:public"],
    deps = [
        "//location:location_ts_proto",
    ],
)

The //:greeting_ts_proto target is effectively a js_library target that can be used as a dependency. For example:

load("@aspect_rules_esbuild//esbuild:defs.bzl", "esbuild")

esbuild(
    name = "program",
    entry_point = "program.mjs",
    deps = [
        #":greeting_ts_proto",
        "//location:location_ts_proto",
        "//:node_modules/google-protobuf",
    ],
)

// file: program.mjs

import { Position } from "./location/location_pb.mjs";

const pos = new Position();
pos.setLatitude(42.42);
console.log("request.latitude = %s", pos.getLatitude());

For more examples that can be copy pasted into your project, look at examples workspaces in the e2e folder.

How it works

Some commentary on how rules_ts_proto works:

1. The basic code generators and runtime libraries used by rules_ts_proto come from a fork of Google's protobuf-javascript and grpc-web.
2. The files produced by rules_ts_proto are ES6 modules, not CommonJS modules.
3. rules_ts_proto produces output files within the bazel package where the target appears (not child directories).
4. A ts_proto_library has a single corresponding proto_library. This proto_library must have a single .proto file in its srcs list, a restriction that should be removed at some point.
5. For each proto_library dep, there should be a corresponding ts_proto_library dep in the ts_proto_library target. There are no restructions on where the ts_proto_library deps are within the workspace. ts_rules_proto will ensure the generated code's imports are correct.
6. For code generated for a given .proto file, rules_ts_proto uses relative imports to import proto dependencies. The TsProtoInfo provider attached to each ts_proto_library keeps track of the association between an input .proto file and the generated JavaScript and TypeScript files. The implementation of the ts_proto_library rule combines the TsProtoInfo values of all dependencies and feeds this info into the custom protoc plugin as a JSON "configuration." The custom protoc plugin in turn calls the protobuf-javascript and grpc-web protoc plugins. The imports generated by these subordinate plugins must be amended using the configuration.

Notes on generated import statements

The majority of the complexity in this library comes from how imports work in the world of TypeScript and JavaScript.

From the NodeJS documentation

NodeJS documentation of ECMASCript modules has an import specifiers section. It defines three types of import specifiers. One of them is

Relative specifiers like './startup.js' or '../config.mjs'. They refer to a path relative to the location of the importing file. The file extension is always necessary for these.

rules_ts_proto generates relative import statements that use absolute extensions for this reason.

See also

• TypeScript's module resolution page