feat: add example of using proto_library with Node.js (#2767)

alexeagle · web-flow · commit 8c7dfcd6d490 · 2026-03-12T12:24:05.000-07:00
Also fix a bug where `js_library` deps ran the proto aspect, but js_binary/js_test did not. /cc @acozzette
diff --git a/.aspect/workflows/config.yaml b/.aspect/workflows/config.yaml
@@ -147,6 +147,9 @@ workspaces:
     # e2e/update_pnpm_lock_with_import:
     # e2e/webpack_devserver:
     # e2e/webpack_devserver_esm:
+    examples/proto:
+        icon: protobuf
+        tasks: *e2e_tasks
 bazel:
     flags:
         - --config=ci
diff --git a/.bazelignore b/.bazelignore
@@ -1,5 +1,6 @@
 # Nested modules
 e2e/
+examples/proto
 
 # TODO(bazel 8): move to REPO.bazel
 examples/js_binary/node_modules/
@@ -20,6 +21,8 @@ examples/npm_package/packages/pkg_d/node_modules/
 examples/npm_package/packages/pkg_e/node_modules/
 examples/runfiles/node_modules
 examples/stack_traces/node_modules
+examples/proto/node_modules
+examples/proto/tools/node_modules
 examples/vite3/node_modules
 examples/vite6/node_modules
 examples/webpack_cli/node_modules/
diff --git a/.gitattributes b/.gitattributes
@@ -6,3 +6,4 @@ js/private/watch/aspect_watch_protocol.mjs linguist-generated=true
 js/private/watch/aspect_watch_protocol.d.mts linguist-generated=true
 js/private/node-patches/fs.cjs linguist-generated=true
 js/private/js_image_layer.mjs linguist-generated=true
+**/*_pb.d.ts linguist-generated=true
diff --git a/.prettierignore b/.prettierignore
@@ -1,6 +1,7 @@
 **/pnpm-lock.yaml
 e2e/**/*-docs.md
 examples/**/*-docs.md
+examples/**/*_pb.d.ts
 js/private/coverage/coverage.js
 js/private/devserver/js_run_devserver.mjs
 js/private/node-patches/fs.cjs
diff --git a/examples/proto/.bazelrc b/examples/proto/.bazelrc
@@ -0,0 +1,2 @@
+build --incompatible_enable_proto_toolchain_resolution
+build --@protobuf//bazel/toolchains:prefer_prebuilt_protoc
diff --git a/examples/proto/.npmrc b/examples/proto/.npmrc
@@ -0,0 +1 @@
+hoist=false
diff --git a/examples/proto/.nvmrc b/examples/proto/.nvmrc
@@ -0,0 +1 @@
+24.11.0
diff --git a/examples/proto/BUILD.bazel b/examples/proto/BUILD.bazel
@@ -0,0 +1,20 @@
+load("@aspect_rules_js//js:defs.bzl", "js_test")
+load("@npm//:defs.bzl", "npm_link_all_packages")
+load("@protobuf//bazel:proto_library.bzl", "proto_library")
+
+npm_link_all_packages()
+
+proto_library(
+    name = "foo_proto",
+    srcs = [
+        "status.proto",
+        "user.proto",
+    ],
+    deps = ["@protobuf//:timestamp_proto"],
+)
+
+js_test(
+    name = "test",
+    data = [":foo_proto"],
+    entry_point = "test_proto.js",
+)
diff --git a/examples/proto/MODULE.bazel b/examples/proto/MODULE.bazel
@@ -0,0 +1,26 @@
+bazel_dep(name = "aspect_rules_js")
+bazel_dep(name = "diff.bzl", version = "0.4.3")
+bazel_dep(name = "protobuf", version = "33.4")  # Works with Bazel 7-9
+bazel_dep(name = "rules_nodejs", version = "6.7.3")
+
+local_path_override(
+    module_name = "aspect_rules_js",
+    path = "../..",
+)
+
+node = use_extension("@rules_nodejs//nodejs:extensions.bzl", "node")
+node.toolchain(node_version_from_nvmrc = "//:.nvmrc")
+
+pnpm = use_extension("@aspect_rules_js//npm:extensions.bzl", "pnpm")
+pnpm.pnpm(pnpm_version_from = "//:package.json")
+use_repo(pnpm, "pnpm")
+
+npm = use_extension("@aspect_rules_js//npm:extensions.bzl", "npm")
+npm.npm_translate_lock(
+    name = "npm",
+    npmrc = "//:.npmrc",
+    pnpm_lock = "//:pnpm-lock.yaml",
+)
+use_repo(npm, "npm")
+
+register_toolchains("//tools/toolchains:all")
diff --git a/examples/proto/package.json b/examples/proto/package.json
@@ -0,0 +1,8 @@
+{
+    "private": true,
+    "packageManager": "pnpm@10.20.0",
+    "dependencies": {
+        "@bufbuild/protobuf": "catalog:"
+    },
+    "type": "module"
+}
diff --git a/examples/proto/pnpm-lock.yaml b/examples/proto/pnpm-lock.yaml
diff --git a/examples/proto/pnpm-workspace.yaml b/examples/proto/pnpm-workspace.yaml
@@ -0,0 +1,8 @@
+packages:
+    - tools
+
+catalog:
+    '@bufbuild/protobuf': '2.7.0'
+    '@types/node': '24'
+
+onlyBuiltDependencies: []
diff --git a/examples/proto/status.proto b/examples/proto/status.proto
@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+import "google/protobuf/timestamp.proto";
+
+package status;
+
+message Status {
+    google.protobuf.Timestamp created_at = 1;
+}
diff --git a/examples/proto/test_proto.js b/examples/proto/test_proto.js
@@ -0,0 +1,14 @@
+import { UserSchema } from './user_pb.js'
+import { StatusSchema } from './status_pb.js'
+import { create, fromBinary, toBinary } from '@bufbuild/protobuf'
+import assert from 'node:assert'
+
+let msg = create(UserSchema, {
+    name: 'hello world',
+    status: create(StatusSchema, { createdAt: new Date() }),
+})
+
+// Reference the inherited `.toBinary()` to ensure types from transitive types are included.
+msg = fromBinary(UserSchema, toBinary(UserSchema, msg))
+
+assert.equal(msg.name, 'hello world')
diff --git a/examples/proto/tools/package.json b/examples/proto/tools/package.json
@@ -0,0 +1,7 @@
+{
+    "devDependencies": {
+        "@bufbuild/protoc-gen-es": "~2.2.4",
+        "@connectrpc/protoc-gen-connect-query": "^2.0.1",
+        "@types/node": "catalog:"
+    }
+}
diff --git a/examples/proto/tools/toolchains/BUILD b/examples/proto/tools/toolchains/BUILD
@@ -0,0 +1,28 @@
+load("@aspect_rules_js//js:proto.bzl", "js_proto_toolchain")
+load("@npm//tools:@bufbuild/protoc-gen-es/package_json.bzl", gen_es = "bin")
+load("@npm//tools:@connectrpc/protoc-gen-connect-query/package_json.bzl", gen_connect_query = "bin")
+
+gen_es.protoc_gen_es_binary(
+    name = "protoc_gen_es",
+)
+
+# FIXME: wire this up to another toolchain_type symbol?
+gen_connect_query.protoc_gen_connect_query_binary(
+    name = "protoc_gen_connect_query",
+)
+
+js_proto_toolchain(
+    name = "example_protoc_plugin",
+    plugin_bin = ":protoc_gen_es",
+    plugin_name = "es",
+    # See https://github.com/connectrpc/connect-es/blob/main/MIGRATING.md#update-plugin-options
+    # and https://github.com/bufbuild/protobuf-es/tree/main/packages/protoc-gen-es#plugin-options
+    plugin_options = [
+        "keep_empty_files=true",
+        "target=js+dts",
+        "import_extension=js",
+    ],
+    # NB: this must be a parent folder of any package that use the toolchain
+    # Otherwise typescript won't resolve a dep from the generated code in that package to the @bufbuild/protobuf package
+    runtime = "//:node_modules/@bufbuild/protobuf",
+)
diff --git a/examples/proto/user.proto b/examples/proto/user.proto
@@ -0,0 +1,9 @@
+syntax = "proto3";
+
+import "status.proto";
+
+message User {
+    string name = 1;
+    status.Status status = 2;
+    repeated string tags = 3;
+}
diff --git a/js/private/js_binary.bzl b/js/private/js_binary.bzl
@@ -21,6 +21,7 @@ load("@bazel_lib//lib:expand_make_vars.bzl", "expand_locations", "expand_variabl
 load("@bazel_lib//lib:windows_utils.bzl", "create_windows_native_launcher_script")
 load(":bash.bzl", "BASH_INITIALIZE_RUNFILES")
 load(":js_helpers.bzl", "LOG_LEVELS", "envs_for_log_level", "gather_files_from_js_infos", "gather_runfiles")
+load(":proto.bzl", "js_proto_aspect")
 
 _DOC = """Execute a program in the Node.js runtime.
 
@@ -99,6 +100,7 @@ _ATTRS = {
         NB: `data` files are copied to the Bazel output tree before being passed
         as inputs to runfiles. See `copy_data_to_bin` docstring for more info.
         """,
+        aspects = [js_proto_aspect],
     ),
     "entry_point": attr.label(
         allow_files = True,

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,2 @@`
	`1`	`+build --incompatible_enable_proto_toolchain_resolution`
	`2`	`+build --@protobuf//bazel/toolchains:prefer_prebuilt_protoc`