Protobuf-ES

Protobuf-ES is Buf’s implementation of Protocol Buffers for JavaScript and TypeScript, built around plain message objects, native TypeScript types, and a standard protoc/Buf CLI plugin (protoc-gen-es) rather than a bespoke codegen wrapper. It targets full conformance with the official Protobuf test suite, supports proto3 and Edition 2024, and produces spec-compliant JSON (using native bigint for 64-bit integers instead of a Long.js shim).

The project ships as a small set of companion packages: @bufbuild/protobuf (the runtime with message APIs, JSON/binary serialization, reflection, and registries), @bufbuild/protoc-gen-es (the code-generation plugin), and @bufbuild/protoplugin (a framework for authoring custom Protobuf plugins). It pairs with connect-es for gRPC/gRPC-Web/Connect RPC on top of the same generated types, and is positioned as a modern, ESM-native alternative to google-protobuf and protobuf.js.

What You Get

• A runtime (@bufbuild/protobuf) with create, fromBinary/toBinary, fromJson/toJson, reflection, and registries for messages and extensions
• protoc-gen-es, a standard protoc/Buf CLI plugin that generates plain-object TypeScript types plus schema descriptors
• @bufbuild/protoplugin, a framework for writing custom Protobuf code-generation plugins in TypeScript
• Support for proto3 and Protobuf Editions (2023/2024), including typed extensions and discriminated-union oneofs
• Spec-compliant JSON serialization using native bigint for 64-bit integers instead of Long.js

Common Use Cases

• Generating typed TypeScript models from .proto schemas for use across a frontend and backend
• Building gRPC, gRPC-Web, or Connect RPC clients/servers in TypeScript alongside connect-es
• Migrating an existing google-protobuf or protobuf.js codebase to a modern, ESM-native Protobuf runtime
• Writing custom Protobuf code generators on top of @bufbuild/protoplugin

Under The Hood

Architecture The repository is a Turborepo/npm-workspaces monorepo under packages/: protobuf holds the runtime (message creation, binary/JSON codecs, reflection, well-known types under src/wkt), protoc-gen-es is the standalone code-generation plugin, and protoplugin provides the framework that both protoc-gen-es and third-party plugins are built on. Conformance is validated in a dedicated protobuf-conformance integration against the upstream Google conformance test suite, and protobuf-test/protoplugin-test hold cross-package integration tests separate from each package’s own unit tests.

Tech Stack Written entirely in TypeScript (96% of the codebase), built with tshy for dual ESM/CJS output, linted and formatted with Biome, and versioned/released via Turborepo pipelines. The only non-Apache-2.0 code is the varint wire-format routine, carried over from Google’s original BSD-3-Clause-licensed implementation.

Code Quality The project runs the official Protobuf conformance test suite (0 required-test failures as of the reviewed release) in addition to its own unit and integration tests across protobuf-test and protoplugin-test, giving it stronger correctness guarantees than most JS Protobuf implementations. Reflection, registries, and extensions are implemented as first-class, tested APIs rather than bolted-on afterthoughts.

API Design The public API centers on plain message objects plus free functions (create, fromBinary, toBinary, fromJson, toJson) operating on a schema object, rather than generated classes with getter/setter methods — a deliberate departure from google-protobuf’s API shape that the README documents with an explicit migration table. Oneofs are exposed as discriminated unions (switch (msg.result.case)) instead of a maze of per-case getters, reducing boilerplate for consumers of generated types.