import { create, fromBinary, toBinary, toJson } from "@bufbuild/protobuf";
import { type User, UserSchema } from "./gen/user/v1/user_pb";

// Messages are plain objects: pass fields in an initializer, or set them later.
const user: User = create(UserSchema, {
  id: "123",
  firstName: "Alice",
});
user.lastName = "Smith";

// Serialize to the Protobuf wire format, then parse it back.
const wire = toBinary(UserSchema, user);
user = fromBinary(UserSchema, wire);

console.log(user.firstName);           // Alice
console.log(toJson(UserSchema, user))  // {"id": "123", "firstName": "Alice", "lastName": "Smith"}

Protobuf is the easiest way to build APIs. We recommend using it with Connect, which gives you type-safe clients and servers in every major language, and interoperates seamlessly with gRPC.

Here's what the client looks like:

import { createClient } from "@connectrpc/connect";
import { createConnectTransport } from "@connectrpc/connect-web";
import { UserService } from "./gen/user/v1/user_pb.js";

const client = createClient(
  UserService,
  createConnectTransport({
    baseUrl: "http://localhost:8080",
  })
);

const response = await client.getUser({ id: "123" });
console.log(response.user.firstName); // Alice

And the server:

import { ConnectRouter } from "@connectrpc/connect";
import { UserService } from "./gen/user/v1/user_pb.js";

export default (router: ConnectRouter) => {
  router.service(UserService, {
    async getUser(request) {
      const user = { id: request.id, firstName: "Alice", lastName: "Smith" };
      return { user };
    },
  });
}

Serve it with Fastify, Next.js, Express, and more.

Quickstart

// proto/user/v1/user.proto
syntax = "proto3";

package user.v1;

service UserService {
  rpc GetUser(GetUserRequest) returns (GetUserResponse);
}

message GetUserRequest {
  string id = 1;
}

message GetUserResponse {
  User user = 1;
}

message User {
  string id = 1;
  string first_name = 2;
  string last_name = 3;
}

# buf.gen.yaml
version: v2
inputs:
  - directory: proto
plugins:
  - local: protoc-gen-es
    out: src/gen
    opt: target=ts

$ npm install @bufbuild/protobuf @connectrpc/connect
$ npm install --save-dev @bufbuild/protoc-gen-es @bufbuild/buf
$ npx buf generate

That's all - typed messages and Connect stubs now live in src/gen.

Features

• Generates pure TypeScript
• Plain message objects, no getters/setters
• Reflection, registries, and custom options
• 100% conformant against the official Protobuf test suite
• Standard plugin-based generation, works with the Buf CLI as well as protoc
• Write your own code generators with @bufbuild/protoplugin
• Pairs with @connectrpc/connect for RPC and @bufbuild/protovalidate for validation

How it compares

• google-protobuf uses a dated getter/setter API and requires third-party plugins for TypeScript.
• protobuf.js is a complicated library with three runtimes and three codegen targets. It requires extra configuration to be completely conformant, and is not type-safe under some configurations.

Documentation

• protobufes.com: Complete guide to code generation, messages, JSON, reflection, registries, extensions, and migration.
• Code example: A working example that uses generated Protobuf types in application code.
• Plugin example: Example plugin that generates Twirp clients.
• Conformance results: Public runner and comparison table.
• Bundle size comparison: Side-by-side numbers against Google's generator.
• connect-es: Companion RPC library for Connect, gRPC, and gRPC-Web.

Packages

• @bufbuild/protobuf: Runtime library with message APIs, well-known types, JSON, reflection, registries, and extensions.
• @bufbuild/protoc-gen-es: Standard Protobuf plugin for TypeScript and JavaScript generation.
• @bufbuild/protoplugin: Framework for writing your own Protobuf plugins in TypeScript.

Compatibility

• Baseline web browsers from the last 2.5 years are supported.
• Node.js: All maintained releases are supported.
• Deno: Latest LTS release is supported.
• Bun: Latest v1 release is supported.
• TypeScript: Versions less than 2 years old are supported with 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.