\n\n**Protocol Buffers** are a language-neutral, platform-neutral, extensible way of serializing structured data for use in communications protocols, data storage, and more, originally designed at Google ([see](https://protobuf.dev/)).\n\n**protobuf.js** is a very fast, conformant, and unusually versatile JavaScript implementation of Protocol Buffers for Node.js and browsers. It works with `.proto` files out of the box, does not require protoc, and supports runtime reflection as well as specialized code generation with strong TypeScript declarations.\n\nIf protobuf.js is important to your project or organization, or if you depend on it commercially, [consider supporting](https://github.com/sponsors/dcodeIO) its ongoing maintenance. Sponsorship helps make bug fixes, releases, LTS/security handling, and user support more sustainable.\n\n## Getting started\n\nGetting up and running is simple: Install the package, load a `.proto` file, and you are all set to encode and decode Protobuf messages. From there, protobuf.js grows with your requirements: Add any combination of capabilities, such as [code generation](#code-generation), [TypeScript declarations](#typescript-integration), [transport-agnostic services](#services), [programmatic schemas](#programmatic-schemas), [optional extensions](#extensions), and more as needed. All in one flexible toolkit.\n\n### Install\n\n```sh\nnpm install protobufjs\n```\n\nThe [command line utility](./cli/#readme) for generating reflection bundles, static code and TypeScript declarations is published as an add-on package:\n\n```sh\nnpm install --save-dev protobufjs-cli\n```\n\nThe CLI is a JS-native protobuf.js toolchain that does not require setting up `protoc`. If you prefer a `protoc`-based workflow, it provides `protoc-gen-pbjs` as an option.\n\n#### Browser builds\n\nCanonical browser builds for each runtime variant are [provided via the jsDelivr CDN](https://cdn.jsdelivr.net/npm/protobufjs@8.X.X/dist/), supporting CommonJS, AMD and global `window.protobuf`. Make sure to pin an exact version in production.\n\n## Usage\n\nThe examples below use this schema:\n\n```proto\nsyntax = \"proto3\";\n\npackage awesomepackage;\n\nmessage AwesomeMessage {\n string awesome_field = 1;\n}\n```\n\nprotobuf.js converts `.proto` field names to camelCase by default, so `awesome_field` is used as `awesomeField` in JavaScript. Use the `keepCase` option when loading or parsing `.proto` files to preserve field names as written.\n\n### Load a schema\n\n```ts\nconst protobuf = require(\"protobufjs\");\n\nconst root = await protobuf.load(\"awesome.proto\");\nconst AwesomeMessage = root.lookupType(\"awesomepackage.AwesomeMessage\");\n```\n\nOptionally use `load()` with a callback, or `loadSync()` for synchronous loading on Node.js. Imports resolve relative to the importing file by default. To resolve imports against a specific base directory, create a `Root` and override `root.resolvePath` before calling `root.load()`.\n\n### Encode and decode\n\n```ts\nconst payload = { awesomeField: \"hello\" };\n\n// Optionally create a message instance from already valid data\nconst message = AwesomeMessage.create(payload);\n\nconst encoded = AwesomeMessage.encode(message).finish();\nconst decoded = AwesomeMessage.decode(encoded);\n```\n\n`encode` expects a message instance or equivalent plain object and does not verify input implicitly. Use `create` to create a message instance from already valid data when useful, `verify` for plain objects whose shape is not guaranteed, and `fromObject` when conversion from broader JavaScript objects is needed.\n\nPlain objects can be encoded directly when they already use protobuf.js runtime types: numbers for 32-bit numeric fields, booleans for `bool`, strings for `string`, `Uint8Array` or `Buffer` for `bytes`, arrays for repeated fields, and plain objects for maps. Map keys are the string representation of the respective value or an 8-character hash string for 64-bit keys.\n\nUnknown fields present on the wire are discarded by default. To preserve and forward unknown fields, set `reader.discardUnknown = false` before decoding with that reader, or make this the default for subsequently created readers with `Reader.discardUnknown = false`. Preserved unknown field data can be dropped from a decoded message with `delete message.$unknowns`.\n\n### Convert plain objects\n\nConversion is an explicit interoperability boundary. `fromObject` accepts common JavaScript inputs such as enum values by name, base64 bytes, decimal 64-bit strings, `Long`, and `BigInt`; `toObject` lets callers choose the output expected by their application or transport.\n\n```ts\nconst message = AwesomeMessage.fromObject({ awesomeField: 42 });\nconst object = AwesomeMessage.toObject(message, {\n longs: String,\n enums: String,\n bytes: String\n});\n```\n\nCommon `ConversionOptions` are:\n\n| Option | Effect |\n|--------|--------|\n| `longs: BigInt` | Converts 64-bit values to bigint values |\n| `longs: String` | Converts 64-bit values to decimal strings |\n| `longs: Number` | Converts 64-bit values to JS numbers (may lose precision) |\n| `enums: String` | Converts enum values to names |\n| `bytes: String` | Converts bytes to base64 strings |\n| `defaults: true` | Includes default values for unset fields |\n| `arrays: true` | Includes empty arrays for repeated fields |\n| `objects: true` | Includes empty objects for map fields |\n| `oneofs: true` | Includes virtual oneof discriminator properties |\n\n## Message API\n\nMessage types expose focused methods for validation, conversion, and binary I/O.\n\n* **encode**(message: `Message | object`, writer?: `Writer`): `Writer` \n Encodes a message or equivalent plain object. Call `.finish()` on the returned writer to obtain a buffer.\n\n* **encodeDelimited**(message: `Message | object`, writer?: `Writer`): `Writer` \n Encodes a length-delimited message.\n\n* **decode**(reader: `Reader | Uint8Array`): `Message` \n Decodes a message from protobuf binary data.\n\n* **decodeDelimited**(reader: `Reader | Uint8Array`): `Message` \n Decodes a length-delimited message.\n\n* **create**(properties?: `object`): `Message` \n Creates a message instance from already valid data.\n\n* **verify**(object: `object`): `null | string` \n Checks whether a plain object can be encoded as-is. Returns `null` if valid, otherwise an error message.\n\n* **fromObject**(object: `object`): `Message` \n Converts broader JavaScript input into a message instance.\n\n* **toObject**(message: `Message`, options?: `ConversionOptions`): `object` \n Converts a message instance to a configurable plain JavaScript object.\n\n* **message.toJSON**(): `object` \n Converts a message instance to JSON-compatible output using default conversion options.\n\nMessage instances provide runtime identity, so they can be tested with `instanceof`. Their `toJSON` method integrates them with `JSON.stringify`.\n\nLength-delimited methods read and write a varint byte length before the message, which is useful for streams and framed protocols.\n\nIf required fields are missing while decoding proto2 data, `decode` throws `protobuf.util.ProtocolError` with the partially decoded message available as `err.instance`.\n\n## Runtimes\n\nprotobuf.js provides three runtime entry points, keeping parser and reflection support optional: Runtime `.proto` loading needs the parser, JSON/reflection bundles need reflection support, and generated static modules only need the minimal runtime.\n\n| Import | Includes | Use when\n| ----------------------- | ------------------ | --------\n| `protobufjs` | Reflection, Parser | You load `.proto` files at runtime\n| `protobufjs/light.js` | Reflection | You load JSON bundles or build schemas programmatically\n| `protobufjs/minimal.js` | Static runtime | You use generated static code\n\nThe full build includes the light build, and the light build includes the minimal runtime.\n\n## Code generation\n\nUse [`protobufjs-cli`](./cli/#readme) to generate reflection bundles, static JavaScript code, and matching TypeScript declarations, either directly with `pbjs` or through the optional `protoc-gen-pbjs` plugin for `protoc`.\n\nReflection keeps schemas as JSON metadata and generates optimized functions at runtime. Static code emits schema-specific, reflection-free functions ahead of time. The main tradeoffs are how schemas are loaded, how bundle size scales with schema size, and whether reflection metadata should remain available at runtime.\n\n| Target | Output | Minimum Runtime |\n|--------|--------|-----------------|\n| `json` | JSON bundle | `protobufjs/light.js` |\n| `json-module` | JSON bundle module | `protobufjs/light.js` |\n| `static-module` | Static code module | `protobufjs/minimal.js` |\n\nModule targets support `--wrap default` for CommonJS and AMD, plus `esm`, `commonjs`, `amd`, and `closure`; `--wrap` can also load a custom wrapper module.\n\n### Static modules\n\nStatic modules emit dedicated JavaScript for your schema, so they only need `protobufjs/minimal.js` at runtime.\n\n```sh\nnpx pbjs -t static-module -w esm -o awesome.js --dts awesome.proto\n```\n\n```ts\nimport { awesomepackage } from \"./awesome.js\";\n\nconst message = awesomepackage.AwesomeMessage.create({ awesomeField: \"hello\" });\n```\n\nWhile static code is verbose by design, its repeated patterns compress well with Brotli or gzip, and it works in [CSP](https://w3c.github.io/webappsec-csp/)-restricted environments that disallow unsafe-eval without sacrificing performance.\n\n### Reflection bundles\n\nReflection bundles store schemas as compact JSON metadata, avoiding `.proto` parsing at runtime and letting browsers load schema metadata in one request. While they require at least `protobufjs/light.js`, large schemas can produce smaller combined bundles than equivalent static modules because common code is shared through reflection.\n\n```sh\nnpx pbjs -t json -o awesome.json awesome1.proto awesome2.proto ...\n```\n\n```ts\nconst bundle = require(\"./awesome.json\");\n\nconst root = protobuf.Root.fromJSON(bundle);\nconst AwesomeMessage = root.lookupType(\"awesomepackage.AwesomeMessage\");\n```\n\n```sh\nnpx pbjs -t json-module -w esm -o awesome.js --dts awesome.proto\n```\n\n```ts\nimport { awesomepackage } from \"./awesome.js\";\n\nconst AwesomeMessage = awesomepackage.AwesomeMessage;\n```\n\nJSON modules export the reflection root and, with `-w esm`, also provide top-level named exports that align with static modules. Their declarations mirror `static-module` typings, but because JSON modules are backed by reflection objects, message instances should be created with `MyMessage.create(...)` instead of constructors. Code using `create(...)` works with static modules as well.\n\n### TypeScript integration\n\nprotobuf.js works with TypeScript out of the box: the runtime API is typed, and generated JavaScript can be paired with strong TypeScript declarations in the same CLI invocation. Generated output is directly usable from JavaScript without a transpile step, and strongly typed in TypeScript projects, with type-checked oneofs and JavaScript-friendly plain-object input.\n\nFor example, given the oneof:\n\n```proto\nmessage Profile {\n oneof contact {\n string email = 1;\n string phone = 2;\n }\n}\n```\n\nGenerated declarations narrow both the `contact` oneof and the concrete values:\n\n```ts\nconst profile = Profile.create({\n contact: \"email\",\n email: \"hello@example.com\"\n});\n\nif (profile.contact === \"email\") {\n profile.email; // string\n}\n\nconst decoded = Profile.decode(bytes);\nif (decoded.contact === \"phone\") {\n decoded.phone; // string\n}\n```\n\nPlain objects can use the same narrowed shape through a collision-free scoped type:\n\n```ts\nconst object: Profile.$Shape = {\n contact: \"email\",\n email: \"hello@example.com\"\n};\n```\n\n## Advanced usage\n\n### Programmatic schemas\n\nThe full and light builds can construct schemas directly through reflection:\n\n```ts\nconst AwesomeMessage = new protobuf.Type(\"AwesomeMessage\")\n .add(new protobuf.Field(\"awesomeField\", 1, \"string\"));\n\nconst root = new protobuf.Root()\n .define(\"awesomepackage\")\n .add(AwesomeMessage);\n```\n\n### Custom message classes\n\nA reflected type can use a custom class as its runtime constructor:\n\n```ts\nclass AwesomeMessage extends protobuf.Message {\n awesomeField = \"\";\n\n constructor(properties?: protobuf.Properties) {\n super(properties);\n // ...\n }\n\n customInstanceMethod() {\n return this.awesomeField.toLowerCase();\n }\n}\n\nroot.lookupType(\"awesomepackage.AwesomeMessage\").ctor = AwesomeMessage;\n\nconst decoded = AwesomeMessage.decode(bytes);\ndecoded.customInstanceMethod(); // string\n```\n\nprotobuf.js will populate the constructor with the usual static runtime methods and use it for decoded messages. When assigning constructors manually, add the type to its parent namespace/root first if fields reference other reflected types. In TypeScript, custom members are visible when using the custom class type in consuming code.\n\n### Services\n\nprotobuf.js supports service clients built from service definitions. The service API is transport-agnostic: provide an `rpcImpl` function to connect it to HTTP, WebSocket, gRPC, or another transport.\n\n```js\nfunction myRpcImpl(method, requestData, callback) {\n // method.name\n // method.path\n // method.requestStream?\n // method.responseStream?\n performRequest(requestData, function(err, responseData) {\n callback(err, responseData);\n });\n}\n\nconst myService = MyService.create(myRpcImpl/*, requestDelimited?, responseDelimited? */);\n```\n\nSee [examples/streaming-rpc.js](./examples/streaming-rpc.js) for a streaming example.\n\nIntegration example with [@grpc/grpc-js](https://www.npmjs.com/package/@grpc/grpc-js):\n\n```js\nconst grpc = require('@grpc/grpc-js');\n\nconst Client = grpc.makeGenericClientConstructor({});\nconst client = new Client(serverAddress, grpc.credentials.createInsecure());\n\nconst rpcImpl = (method, requestData, callback) =>\n client.makeUnaryRequest(method.path, (data) => data, (data) => data, requestData, callback);\n\nconst greeter = root.lookupService(\"example.Greeter\").create(rpcImpl);\nconst reply = await greeter.sayHello({ name: \"world\" });\n```\n\nSee [examples/grpc-service.js](./examples/grpc-service.js) for a complete example.\n\n### Extensions\n\nThe following extensions provide descriptor conversion and text-based protobuf formats when reflection metadata is available. Most applications only need the binary APIs above.\n\n#### Descriptors\n\nprotobuf.js uses a compact JSON-based reflection representation internally that is easy to embed and fast to parse, so schemas can be loaded directly without first decoding binary descriptor blobs or postprocessing their full JSON representation. See [ext/descriptor](./ext/README.md#descriptor) for use cases that need conversion between reflected roots and `protoc` descriptor messages.\n\n#### ProtoJSON\n\nProtocol Buffers support a special [ProtoJSON format](https://protobuf.dev/programming-guides/json/) to share data with systems that do not support the binary wire format, for example when implementing gateways. Spec-compliant ProtoJSON is supported via [ext/protojson](./ext/README.md#protojson).\n\n#### Text Format\n\nProtocol Buffers [Text Format](https://protobuf.dev/reference/protobuf/textformat-spec/) is a special syntax for representing protobuf data in text form, which can be useful for configurations or tests. Spec-compliant Text Format is supported via [ext/textformat](./ext/README.md#textformat).\n\n## Conformance\n\nprotobuf.js is validated against the official Protocol Buffers conformance suite, achieving complete binary wire-format conformance for **Proto2**, **Proto3** and **Editions**, plus complete **ProtoJSON** and **Text Format** conformance in its default configuration with reflection metadata present.\n\n\n\n| Category | Total | Required | Recommended |\n| ---------- | ------------------: | ------------------: | ------------------: |\n| Binary | 100.00% (2835/2835) | 100.00% (1958/1958) | 100.00% (877/877) |\n| ↳ Proto2 | 100.00% (707/707) | 100.00% (489/489) | 100.00% (218/218) |\n| ↳ Proto3 | 100.00% (707/707) | 100.00% (486/486) | 100.00% (221/221) |\n| ↳ Editions | 100.00% (1421/1421) | 100.00% (983/983) | 100.00% (438/438) |\n| ProtoJSON | 100.00% (2796/2796) | 100.00% (2362/2362) | 100.00% (434/434) |\n| TextFormat | 100.00% (909/909) | 100.00% (845/845) | 100.00% (64/64) |\n| Overall | 100.00% (6540/6540) | 100.00% (5165/5165) | 100.00% (1375/1375) |\n\n\n\n[Structured results](https://github.com/protobufjs/protobuf.js/actions/workflows/test.yml?query=branch%3Amaster+event%3Apush) are available as CI artifacts. In case of contradicting claims by your favorite LLM, [see](https://dev.to/dcode/when-the-model-is-the-marketing-device-a-protobuf-short-story-2p7p).\n\n## Performance\n\nIn both reflection and reflection-free modes, protobuf.js builds specialized encoders and decoders on top of hand-tuned reader and writer primitives, making it a strong fit from battery-powered devices to high-traffic servers, or generally for projects and their downstream users adopting protobuf as a faster, smaller alternative to JSON.\n\nThe repository includes a [small benchmark](./bench) over a common message shape, plus Mapbox's vector tile fixture and Buf's perf payload, both unmodified. For each case, it compares protobuf.js encode and decode throughput against JSON encode/decode, Google's protoc-gen-js, and Buf's protoc-gen-es. Results show that protobuf.js is consistently faster than the other Protobuf implementations, up to an order of magnitude on real-world data, and among the libraries tested, it is the only one that is an upgrade over using JSON.\n\n\n\n\n\n| Case | protobuf.js static | protobuf.js reflect | JSON | protoc-gen-js | protoc-gen-es |\n| --- | ---: | ---: | ---: | ---: | ---: |\n| Common | 3.18M ops/s | 3.25M ops/s | 2.07M ops/s | 1.01M ops/s | 395K ops/s |\n| Vector tile | 2.82K ops/s | 2.76K ops/s | 859 ops/s | 680 ops/s | 231 ops/s |\n| Buf perf | 41.4K ops/s | 39.9K ops/s | 6.59K ops/s | 13.5K ops/s | 8.00K ops/s |\n\n\n\n| Case | protobuf.js static | protobuf.js reflect | JSON | protoc-gen-js | protoc-gen-es |\n| --- | ---: | ---: | ---: | ---: | ---: |\n| Common | 6.11M ops/s | 6.09M ops/s | 1.31M ops/s | 790K ops/s | 710K ops/s |\n| Vector tile | 2.45K ops/s | 2.78K ops/s | 1.04K ops/s | 858 ops/s | 392 ops/s |\n| Buf perf | 72.5K ops/s | 66.4K ops/s | 19.0K ops/s | 21.1K ops/s | 14.2K ops/s |\n\n\n\n[Structured results](./bench/results/latest.json) of this run are available as committed artifacts.\n\nTo run the benchmark yourself on your own hardware:\n\n```sh\nnpm --prefix bench install\nnpm run bench\n```\n\n## Compatibility\n\nSupported runtimes are browsers, Node.js v12+, Deno and Bun. When using the CLI with Bun, Node.js must also be installed.\n\n## Security\n\nSecurity-impacting reports are handled through coordinated GitHub Security Advisories where appropriate. See [SECURITY.md](./SECURITY.md) for supported release lines and reporting instructions.\n\n## Development\n\n```sh\ngit clone https://github.com/protobufjs/protobuf.js\ncd protobuf.js\nnpm install\nnpm --prefix cli install\n```\n\nRunning the tests:\n\n```sh\nnpm test\n```\n\nBuilding the development and production versions with their respective source maps to `dist/`:\n\n```sh\nnpm run build\n```\n\n## Additional documentation\n\n* [API Documentation](https://protobufjs.github.io/protobuf.js)\n* [Changelog](./CHANGELOG.md)\n* [Protocol Buffers Documentation](https://protobuf.dev/)",
"_attachments": {}
}
![\"protobuf.js\"](\"https://github.com/protobufjs/protobuf.js/raw/master/pbjs.svg\")
![\"\"](\"https://img.shields.io/github/actions/workflow/status/protobufjs/protobuf.js/test.yml?branch=master&label=build&logo=github\")
![\"\"](\"https://img.shields.io/github/actions/workflow/status/protobufjs/protobuf.js/release.yaml?branch=master&label=release&logo=github\")
![\"\"](\"https://img.shields.io/npm/v/protobufjs.svg?logo=npm\")
\n ![\"\"](\"https://img.shields.io/npm/dm/protobufjs.svg?label=downloads&logo=npm\")
\n ![\"\"](\"https://img.shields.io/jsdelivr/npm/hm/protobufjs?label=requests&logo=jsdelivr\")