@bufbuild/protoc-gen-es

What is @bufbuild/protoc-gen-es?

@bufbuild/protoc-gen-es is an npm package that provides a plugin for the Protocol Buffers compiler (protoc) to generate JavaScript and TypeScript code. It is designed to work with the Buf build system and offers a modern, efficient way to handle Protocol Buffers in JavaScript/TypeScript projects.

What are @bufbuild/protoc-gen-es's main functionalities?

Generate JavaScript Code

This feature allows you to generate JavaScript code from your .proto files using the protoc compiler and the @bufbuild/protoc-gen-es plugin. The generated code can then be used in your JavaScript projects.

```json
{
  "scripts": {
    "generate": "protoc --plugin=protoc-gen-es=./node_modules/.bin/protoc-gen-es --es_out=./src --proto_path=./proto ./proto/*.proto"
  }
}
```

Generate TypeScript Code

This feature allows you to generate TypeScript code from your .proto files. The generated TypeScript code can be used in TypeScript projects, providing type safety and better development experience.

```json
{
  "scripts": {
    "generate": "protoc --plugin=protoc-gen-es=./node_modules/.bin/protoc-gen-es --es_out=import_style=typescript,mode=grpcwebtext:./src --proto_path=./proto ./proto/*.proto"
  }
}
```

Integration with Buf

This feature demonstrates how to integrate @bufbuild/protoc-gen-es with the Buf build system. Buf is a tool that helps manage Protocol Buffers, and using it with @bufbuild/protoc-gen-es simplifies the process of generating JavaScript/TypeScript code.

```json
{
  "scripts": {
    "generate": "buf generate"
  }
}
```

Other packages similar to @bufbuild/protoc-gen-es

protobufjs

protobufjs is a popular library for working with Protocol Buffers in JavaScript. It provides a comprehensive set of tools for parsing, serializing, and deserializing Protocol Buffers. Unlike @bufbuild/protoc-gen-es, protobufjs does not require the protoc compiler and can work directly with .proto files or JSON descriptors.

ts-proto

ts-proto is a TypeScript-first Protocol Buffers generator. It generates idiomatic TypeScript code from .proto files, focusing on providing a seamless TypeScript experience. Compared to @bufbuild/protoc-gen-es, ts-proto is more tightly integrated with TypeScript and offers better type safety and developer experience for TypeScript projects.

grpc-tools

grpc-tools is a package that provides the protoc compiler and gRPC plugins for generating code in various languages, including JavaScript and TypeScript. It is a more general-purpose tool compared to @bufbuild/protoc-gen-es, which is specifically designed for the Buf build system and modern JavaScript/TypeScript development.

README

@bufbuild/protoc-gen-es

The code generator plugin for Protocol Buffers for ECMAScript. Learn more about the project at github.com/bufbuild/protobuf-es.

Installation

protoc-gen-es generates base types—messages and enumerations—from your Protocol Buffer schema. The generated code requires the runtime library @bufbuild/protobuf. It's compatible with Protocol Buffer compilers like buf and protoc.

To install the plugin and the runtime library, run:

npm install --save-dev @bufbuild/protoc-gen-es
npm install @bufbuild/protobuf

We use peer dependencies to ensure that the code generator and runtime library are compatible with each other. Note that npm installs them automatically, but Yarn and pnpm do not.

Generating code

With buf

npm install --save-dev @bufbuild/buf

Add a new buf.gen.yaml configuration file:

# Learn more: https://buf.build/docs/configuration/v2/buf-gen-yaml
version: v2
plugins:
  # This will invoke protoc-gen-es and write output to src/gen
  - local: protoc-gen-es
    out: src/gen
    opt:
      # Add more plugin options here
      - target=ts

To generate code for all Protobuf files within your project, run:

npx buf generate

Note that buf can generate from various inputs, not just local Protobuf files.

With protoc

PATH=$PATH:$(pwd)/node_modules/.bin \
  protoc -I . \
  --es_out src/gen \
  --es_opt target=ts \
  a.proto b.proto c.proto

Note that node_modules/.bin needs to be added to the $PATH so that the Protobuf compiler can find the plugin. This happens automatically with npm scripts.

If you use Yarn, versions v2 and above don't use a node_modules directory, so you need to change the variable a bit:

PATH=$(dirname $(yarn bin protoc-gen-es)):$PATH

Plugin options

target

This option controls whether the plugin generates JavaScript, TypeScript, or TypeScript declaration files. Possible values:

• target=js: Generates a _pb.js file for every .proto input file.
• target=ts: Generates a _pb.ts file for every .proto input file.
• target=dts: Generates a _pb.d.ts file for every .proto input file.

You can pass multiple values by separating them with +—for example, target=js+dts.

By default, it generates JavaScript and TypeScript declaration files, which produces the smallest code size and is the most compatible with various bundler configurations. If you prefer to generate TypeScript, use target=ts.

import_extension

By default, protoc-gen-es doesn't add file extensions to import paths. However, some environments require an import extension. For example, using ECMAScript modules in Node.js requires the .js extension, and Deno requires .ts. With this plugin option, you can add .js/.ts extensions in import paths with the given value. Possible values:

• import_extension=none: Doesn't add an extension. (Default)
• import_extension=js: Adds the .js extension.
• import_extension=ts. Adds the .ts extension.

js_import_style

By default, protoc-gen-es generates ECMAScript import and export statements. For use cases where CommonJS is difficult to avoid, this option can be used to generate CommonJS require() calls. Possible values:

• js_import_style=module: Generates ECMAScript import/export statements. (Default)
• js_import_style=legacy_commonjs: Generates CommonJS require() calls.

keep_empty_files=true

By default, protoc-gen-es omits empty files from the plugin output. This option disables pruning of empty files to allow for smooth interoperation with Bazel and similar tooling that requires all output files to be declared ahead of time. Unless you use Bazel, you probably don't need this option.

ts_nocheck=true

protoc-gen-es generates valid TypeScript for current versions of the TypeScript compiler with standard settings. If you use compiler settings that yield an error for generated code, setting this option generates an annotation at the top of each file to skip type checks: // @ts-nocheck.

json_types=true

Generates JSON types for every Protobuf message and enumeration. Calling toJson() automatically returns the JSON type if available. Learn more about JSON types.