> ## 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_js//js:proto.bzl

> Bazel rules_js experimental Protobuf and gRPC support: js_proto_library rule generating JavaScript and TypeScript code from .proto files via protoc plugins.

<Callout icon="book">
  Documentation for [@aspect\_rules\_js@v3.0.3](https://registry.bazel.build/modules/aspect_rules_js/3.0.3) -- <Icon icon="github" iconType="brands" /> [View source](https://github.com/aspect-build/rules_js/blob/v3.0.3/js/proto.bzl)
</Callout>

**EXPERIMENTAL**: Protobuf and gRPC support for JavaScript and TypeScript.

This API is subject to breaking changes outside our usual semver policy.
In a future release of rules\_js this should become stable.

### Typical setup

1. Choose any code generator plugin for protoc.
   In this example we'll show `@bufbuild/protoc-gen-es` that produces both message marshaling and service stubs for JavaScript and TypeScript.
   It should be added as a devDependency in your `package.json`, typically under a `/tools` directory.
   The generator is expected to produce `.js` and `.d.ts` files for each .proto file.
2. Declare a binary target that runs the generator, typically using its package\_json.bzl entry point, for example in `tools/toolchains/BUILD`:

```python theme={null}
load("@npm//tools:@bufbuild/protoc-gen-es/package_json.bzl", gen_es = "bin")
gen_es.protoc_gen_es_binary(name = "protoc_gen_es")
```

3. Define a `js_proto_toolchain` that uses the plugin. See the rule documentation below.
4. Update `MODULE.bazel` to register it, typically with a simple statement like `register_toolchains("//tools/toolchains:all")`

### Usage

Just write `proto_library` targets as usual, or have Gazelle generate them.
Then reference them anywhere a `js_library` could appear, for example:

```python theme={null}
load("@aspect_rules_js//js:defs.bzl", "js_library")
load("@protobuf//bazel:proto_library.bzl", "proto_library")

proto_library(
    name = "eliza_proto",
    srcs = ["eliza.proto"],
)

js_library(
    name = "proto",
    srcs = ["package.json"],
    deps = [":eliza_proto"],
)
```

The generator you setup earlier will be invoked automatically as an action to generate the `.js` and `.d.ts` files.

## Function: `js_proto_toolchain`

Define a proto\_lang\_toolchain that uses the plugin.

Example:

```python theme={null}
js_proto_toolchain(
    name = "gen_es_toolchain",
    plugin_bin = ":protoc_gen_es",
    plugin_name = "es",
    # See 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",
    ],
    runtime = "//:node_modules/@bufbuild/protobuf",
)
```

### Parameters

<ParamField body="name" type="unknown" required>
  The name of the toolchain. A target named \[name]\_toolchain is also created, which is the one to be used in register\_toolchains.
</ParamField>

<ParamField body="plugin_name" type="unknown" required>
  The `NAME` of the plugin program, used in command-line flags to protoc, as follows:

  > `protoc --plugin=protoc-gen-NAME=path/to/mybinary --NAME_out=OUT_DIR`

  See [https://protobuf.dev/reference/cpp/api-docs/google.protobuf.compiler.plugin](https://protobuf.dev/reference/cpp/api-docs/google.protobuf.compiler.plugin)
</ParamField>

<ParamField body="plugin_options" type="unknown" required>
  (List of strings) Command line flags used to invoke the plugin, based on documentation for the generator.

  For example, for `@bufbuild/protoc-gen-es`, reference the documentation at
  [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)
  to arrive at a value like `["import_extension=js"]`
</ParamField>

<ParamField body="plugin_bin" type="unknown" required>
  The plugin to use. This should be the label of a binary target that you declared in step 2 above.
</ParamField>

<ParamField body="runtime" type="unknown" required>
  The runtime to use, which is imported by the generated code. For example, "//:node\_modules/@bufbuild/protobuf".

  Note that node module resolution requires the runtime to be in a parent folder of any package containing generated code.
</ParamField>

<ParamField body="kwargs" type="unknown">
  Additional arguments to pass to the [proto\_lang\_toolchain](https://bazel.build/reference/be/protocol-buffer#proto_lang_toolchain) rule.
</ParamField>