/protobuf-es

Protocol Buffers for ECMAScript. The only JavaScript Protobuf library that is fully-compliant with Protobuf conformance tests.

Primary LanguageTypeScriptApache License 2.0Apache-2.0

The Buf logo

Protobuf-ES

License NPM Version NPM Version NPM Version

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 are Protocol Buffers?

In a nutshell, Protocol Buffers have two main functions:

  • They are a language for writing schemas for your data.
  • They define a binary format for serializing your data.

These two independent traits functions 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:

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;
}

And it is compiled to an ECMAScript class that can be used like this:

let user = new User({
  firstName: "Homer",
  lastName: "Simpson",
  active: true,
  locations: ["Springfield"],
  projects: { SPP: "Springfield Power Plant" },
  manager: {
    firstName: "Montgomery",
    lastName: "Burns",
  },
});

const bytes = user.toBinary();
user = User.fromBinary(bytes);
user = User.fromJsonString('{"firstName": "Homer", "lastName": "Simpson"}');

The benefits can extend to any application that interacts with yours as well. This is 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.

Protocol Buffers also allow you to serialize this structured data. So, 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

  1. Install the code generator, the runtime library, and the Buf CLI:

    npm install @bufbuild/protobuf @bufbuild/protoc-gen-es @bufbuild/buf
  2. Create a buf.gen.yaml file that looks like this:

    # Learn more: https://docs.buf.build/configuration/v1/buf-gen-yaml
    version: v1
    plugins:
       - plugin: es
         opt: target=ts
         out: src/gen
  3. Download the example.proto into a /proto directory:

    mkdir proto
    curl https://raw.githubusercontent.com/bufbuild/protobuf-es/main/packages/protobuf-test/extra/example.proto > proto/example.proto
  4. Generate your code:

    npx buf generate proto

    ** Note you can also use protoc if desired.

You should now see a generated file at src/gen/example_pb.ts that contains a class named User. From here, you can begin to work with your schema.

Packages

Documentation

  • Code example - Example code that uses protocol buffers to manage an address book.
  • Generated Code - How to generate, and what code precisely is generated for any given protobuf definition.
  • Runtime API - A detailed overview of the features provided by the library @bufbuild/protobuf.
  • FAQ - Frequently asked Questions.
  • Migrating to Protobuf-ES - Shows the changes you'll need to switch your existing code base.
  • Writing Plugins - An overview of the process of writing a plugin using @bufbuild/protoplugin.

Ecosystem

TypeScript

The generated code is compatible with TypeScript v4.1.2 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.