{"id":13528262,"url":"https://github.com/bufbuild/protobuf-es","last_synced_at":"2025-04-01T11:31:14.384Z","repository":{"id":36963612,"uuid":"469763813","full_name":"bufbuild/protobuf-es","owner":"bufbuild","description":"Protocol Buffers for ECMAScript. The only JavaScript Protobuf library that is fully-compliant with Protobuf conformance tests.","archived":false,"fork":false,"pushed_at":"2024-04-12T22:25:55.000Z","size":11853,"stargazers_count":923,"open_issues_count":23,"forks_count":51,"subscribers_count":20,"default_branch":"main","last_synced_at":"2024-04-14T11:00:33.075Z","etag":null,"topics":["javascript","protobuf","protoc-plugin","protocol-buffers","schema","typescipt"],"latest_commit_sha":null,"homepage":"","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bufbuild.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":".github/CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":".github/CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null}},"created_at":"2022-03-14T14:14:56.000Z","updated_at":"2024-04-15T12:04:47.507Z","dependencies_parsed_at":"2023-10-14T04:41:31.485Z","dependency_job_id":"9d356227-ddc5-45d2-9764-9e17392d33e3","html_url":"https://github.com/bufbuild/protobuf-es","commit_stats":{"total_commits":237,"total_committers":24,"mean_commits":9.875,"dds":0.5316455696202531,"last_synced_commit":"8748217566c132da3afe6cc4f10974331f42502e"},"previous_names":[],"tags_count":34,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotobuf-es","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotobuf-es/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotobuf-es/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bufbuild%2Fprotobuf-es/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bufbuild","download_url":"https://codeload.github.com/bufbuild/protobuf-es/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246631808,"owners_count":20808761,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["javascript","protobuf","protoc-plugin","protocol-buffers","schema","typescipt"],"created_at":"2024-08-01T06:02:22.037Z","updated_at":"2025-04-01T11:31:14.378Z","avatar_url":"https://github.com/bufbuild.png","language":"TypeScript","funding_links":[],"categories":["TypeScript","javascript"],"sub_categories":[],"readme":"![The Buf logo](./.github/buf-logo.svg)\n\n# Protobuf-ES\n\n[![License](https://img.shields.io/github/license/bufbuild/protobuf-es?color=blue)](./LICENSE) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protobuf/latest?color=green\u0026label=%40bufbuild%2Fprotobuf)](https://www.npmjs.com/package/@bufbuild/protobuf) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protoplugin/latest?color=green\u0026label=%40bufbuild%2Fprotoplugin)](https://www.npmjs.com/package/@bufbuild/protoplugin) [![NPM Version](https://img.shields.io/npm/v/@bufbuild/protoc-gen-es/latest?color=green\u0026label=%40bufbuild%2Fprotoc-gen-es)](https://www.npmjs.com/package/@bufbuild/protoc-gen-es)\n\nA complete implementation of [Protocol Buffers](https://protobuf.dev/) in TypeScript,\nsuitable for web browsers and Node.js, created by [Buf](https://buf.build).\n\nProtobuf-ES is the only fully-compliant JavaScript Protobuf library that passes the\nProtobuf conformance tests—[read more on our blog][blog-post].\n\nProtobuf-ES's companion RPC library is [Connect-ES](https://github.com/connectrpc/connect-es),\nwhich supports the Connect, gRPC, and gRPC-Web protocols.\n\n## What is Protocol Buffers?\n\nIn a nutshell, Protocol Buffers (aka Protobuf) has two main functions:\n\n- It's a language for writing schemas for your data.\n- It defines a binary format for serializing your data.\n\nThese two independent traits work together to allow your project and everyone who interacts with it to define messages,\nfields, and service APIs in the exact same way. In a practical sense as it relates to **Protobuf-ES**, this means no\nmore disparate JSON types all over the place. Instead, you define a common schema in a Protobuf file, such as:\n\n```proto\nsyntax = \"proto3\";\n\nmessage User {\n  string first_name = 1;\n  string last_name = 2;\n  bool active = 3;\n  User manager = 4;\n  repeated string locations = 5;\n  map\u003cstring, string\u003e projects = 6;\n}\n```\n\nYou can then compile it to ECMAScript with `buf` or `protoc`, and use it like this:\n\n```typescript\nimport { UserSchema } from \"./gen/user_pb.js\";\nimport { create, toBinary, toJson } from \"@bufbuild/protobuf\";\n\nlet user = create(UserSchema, {\n  firstName: \"Homer\",\n  lastName: \"Simpson\",\n  active: true,\n  locations: [\"Springfield\"],\n  projects: { SPP: \"Springfield Power Plant\" },\n  manager: {\n    firstName: \"Montgomery\",\n    lastName: \"Burns\",\n  },\n});\n\nconst bytes = toBinary(UserSchema, user);\nconst json = toJson(UserSchema, user);\n```\n\nThe benefits of using Protobuf extend to any application that interacts with yours, because the Protobuf file above\ncan be used to generate types in many languages. The added bonus is that no one has to write any boilerplate code to\nmake this happen. [Code generators](https://www.npmjs.com/package/@bufbuild/protoc-gen-es) handle all of this for you.\n\nProtobuf also allows you to serialize this structured data. Your application running in the browser can send\na `User` object to a backend running an entirely different language, but using the exact same definition. Using an RPC\nframework like [Connect-ES](https://github.com/connectrpc/connect-es), your data is serialized into bytes on the wire\nand then deserialized at its destination using the defined schema.\n\n## Quickstart\n\n1. Install the runtime library, code generator, and the [Buf CLI](https://buf.build/docs/ecosystem/cli-overview):\n\n   ```shellsession\n   npm install @bufbuild/protobuf\n   npm install --save-dev @bufbuild/protoc-gen-es @bufbuild/buf\n   ```\n\n2. Create a `buf.gen.yaml` file that looks like this:\n\n   ```yaml\n   # Learn more: https://buf.build/docs/configuration/v2/buf-gen-yaml\n   version: v2\n   inputs:\n     - directory: proto\n   plugins:\n     - local: protoc-gen-es\n       opt: target=ts\n       out: src/gen\n   ```\n\n3. Download the [example.proto](packages/protobuf-example/proto/example.proto) into a `proto` directory:\n\n   ```shellsession\n   mkdir proto\n   curl https://raw.githubusercontent.com/bufbuild/protobuf-es/main/packages/protobuf-example/proto/example.proto \u003e proto/example.proto\n   ```\n\n4. Generate your code with `buf` or [`protoc`]:\n\n   ```shellsession\n   npx buf generate\n   ```\n\nYou should now see a generated file at `src/gen/example_pb.ts` that contains a type `User`, and a schema `UserSchema`.\nFrom here, you can begin to work with your schema.\n\n## Documentation\n\n- [Manual](MANUAL.md) - Explains all aspects of using Protobuf with ECMAScript.\n- [Code example](packages/protobuf-example) - Example code that uses Protobuf to manage a persistent list of users.\n- [Plugin example](packages/protoplugin-example) - Shows how to write a custom plugin to generate Twirp clients from\n  Protobuf service definitions.\n\n## Packages\n\n- [@bufbuild/protobuf](https://www.npmjs.com/package/@bufbuild/protobuf):\n  Provides the runtime library, containing base types, generated well-known types, and core functionality.\n- [@bufbuild/protoc-gen-es](https://www.npmjs.com/package/@bufbuild/protoc-gen-es):\n  Provides the code generator plugin `protoc-gen-es`. The code it generates depends on `@bufbuild/protobuf`.\n- [@bufbuild/protoplugin](https://www.npmjs.com/package/@bufbuild/protoplugin):\n  Helps to create your own code generator plugin. The code it generates depends on `@bufbuild/protobuf`.\n\n## Ecosystem\n\n- [Connect-ES](https://github.com/connectrpc/connect-es):\n  Type-safe APIs with Protobuf and TypeScript\n- [Connect-ES examples](https://github.com/connectrpc/examples-es):\n  Examples for using Connect with various TypeScript web frameworks and tooling\n- [protobuf-conformance](https://github.com/bufbuild/protobuf-conformance):\n  A repository running the Protobuf conformance tests against various libraries.\n- [Buf Studio](https://buf.build/studio): Web UI for ad-hoc RPCs\n\n## TypeScript compatibility\n\nThe generated code is compatible with TypeScript **v4.9.5** or later, with the default compiler settings.\n\n## Copyright\n\nThe [code to encode and decode varint](packages/protobuf/src/wire/varint.ts) is Copyright 2008 Google Inc., licensed\nunder BSD-3-Clause.\nAll other files are licensed under Apache-2.0, see [LICENSE](LICENSE).\n\n[blog-post]: https://buf.build/blog/protobuf-conformance\n[`protoc`]: MANUAL.md#generate-with-protoc\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fprotobuf-es","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbufbuild%2Fprotobuf-es","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbufbuild%2Fprotobuf-es/lists"}