Protobuf-ES
A complete implementation of Protocol Buffers in TypeScript,
suitable for web browsers and Node.js, created by Buf.
Protobuf-ES is the only fully-compliant JavaScript Protobuf library that passes the
Protobuf conformance tests—read more on our blog.
Protobuf-ES's companion RPC library is Connect-ES,
which supports the Connect, gRPC, and gRPC-Web protocols.
What is Protocol Buffers?
In a nutshell, Protocol Buffers (aka Protobuf) has two main functions:
- It's a language for writing schemas for your data.
- It defines a binary format for serializing your data.
These two independent traits work together to allow your project and everyone who interacts with it to define messages,
fields, and service APIs in the exact same way. In a practical sense as it relates to Protobuf-ES, this means no
more disparate JSON types all over the place. Instead, you define a common schema in a Protobuf file, such as:
syntax = "proto3";
message User {
string first_name = 1;
string last_name = 2;
bool active = 3;
User manager = 4;
repeated string locations = 5;
map<string, string> projects = 6;
}
You can then compile it to ECMAScript with buf or protoc, and use it like this:
import { UserSchema } from "./gen/user_pb.js";
import { create, toBinary, toJson } from "@bufbuild/protobuf";
let user = create(UserSchema, {
firstName: "Homer",
lastName: "Simpson",
active: true,
locations: ["Springfield"],
projects: { SPP: "Springfield Power Plant" },
manager: {
firstName: "Montgomery",
lastName: "Burns",
},
});
const bytes = toBinary(UserSchema, user);
const json = toJson(UserSchema, user);
The benefits of using Protobuf extend to any application that interacts with yours, because the Protobuf file above
can be used to generate types in many languages. The added bonus is that no one has to write any boilerplate code to
make this happen. Code generators handle all of this for you.
Protobuf also allows you to serialize this structured data. Your application running in the browser can send
a User object to a backend running an entirely different language, but using the exact same definition. Using an RPC
framework like Connect-ES, your data is serialized into bytes on the wire
and then deserialized at its destination using the defined schema.
Quickstart
-
Install the code generator, the runtime library, and the Buf CLI:
npm install @bufbuild/protobuf @bufbuild/protoc-gen-es @bufbuild/buf
-
Create a buf.gen.yaml file that looks like this:
# Learn more: https://buf.build/docs/configuration/v2/buf-gen-yaml
version: v2
inputs:
- directory: proto
plugins:
- local: protoc-gen-es
opt: target=ts
out: src/gen
-
Download the example.proto into a proto directory:
mkdir proto
curl https://raw.githubusercontent.com/bufbuild/protobuf-es/main/packages/protobuf-example/proto/example.proto > proto/example.proto
-
Generate your code with buf or protoc:
npx buf generate
You should now see a generated file at src/gen/example_pb.ts that contains a type User, and a schema UserSchema.
From here, you can begin to work with your schema.
Documentation
- Manual - Explains all aspects of using Protobuf with ECMAScript.
- Code example - Example code that uses Protobuf to manage a persistent list of users.
- Plugin example - Shows how to write a custom plugin to generate Twirp clients from
Protobuf service definitions.
Packages
- @bufbuild/protobuf:
Provides the runtime library, containing base types, generated well-known types, and core functionality.
- @bufbuild/protoc-gen-es:
Provides the code generator plugin
protoc-gen-es. The code it generates depends on @bufbuild/protobuf.
- @bufbuild/protoplugin:
Helps to create your own code generator plugin. The code it generates depends on
@bufbuild/protobuf.
Ecosystem
TypeScript compatibility
The generated code is compatible with TypeScript v4.9.5 or later, with the default compiler settings.
Copyright
The code to encode and decode varint is Copyright 2008 Google Inc., licensed
under BSD-3-Clause.
All other files are licensed under Apache-2.0, see LICENSE.
