Registry / serialization / protobufjs

protobufjs

JSON →
library8.0.1jsnpmunverified

Protobuf.js is a comprehensive JavaScript and TypeScript implementation of Protocol Buffers, providing tools for encoding and decoding structured data efficiently. It supports both dynamic (reflection-based) parsing of .proto schemas and static code generation for optimized performance and type safety. The library is actively maintained, with the current stable version being 8.0.1 as of early 2026, and frequent updates addressing bugs and security concerns, alongside less frequent major releases that introduce new features and breaking changes. Protobuf.js aims to be versatile, usable in both Node.js environments and browsers, making it a robust choice for projects requiring high-performance data serialization across different JavaScript runtimes.

npm install protobufjs
INSTALL
IMPORT
SIG · PROTOBUFJS
P
protobufjs
serializationjavascriptv8.0.1
Install
—
Import
—
Disk
—
Pass rate
0/ 6
Env Coverage0 / 6
glibc
18–22
musl
18–22
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18–226 runs
build_error
glibc
node 18–226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

Root
✓ import { Root } from 'protobufjs';
✗ import protobuf from 'protobufjs'; // protobufjs primarily uses named exports, no default export in main bundle
`Root` is the central class for managing and loading Protocol Buffer definitions. `protobufjs` modules are typically imported via named exports for ESM.
load
✓ import { load } from 'protobufjs';
✗ const root = require('protobufjs').loadSync('./my.proto'); // Using CommonJS 'require' in an ESM context, or blocking 'loadSync' in an async flow
`load` is the asynchronous, Promise-based function for loading .proto files, recommended for most applications. `loadSync` is available for synchronous loading but should be used with caution to avoid blocking.
Type
✓ import { Type, Field } from 'protobufjs';
✗ import { MyMessageType } from 'protobufjs'; // Specific message types (e.g., 'MyMessageType') are dynamically resolved from a Root instance or come from generated code, not directly exported by the library.
`Type` and `Field` are used for programmatic definition of Protocol Buffer schemas. When using dynamically loaded .proto files, specific message constructors are obtained via `root.lookupType('Your.Package.MyMessage')`.

This quickstart demonstrates how to programmatically define a simple Protobuf schema using `Root`, `Type`, and `Field`. It then shows the complete flow of creating a message payload, verifying it, encoding it into a binary buffer, and subsequently decoding the buffer back into a JavaScript object, illustrating core serialization capabilities.

import { Root, Type, Field } from 'protobufjs'; // 1. Define a .proto schema programmatically const root = new Root('my_schema_root'); const MyMessage = new Type('MyMessage') .add(new Field('name', 1, 'string')) .add(new Field('id', 2, 'int32')) .add(new Field('isActive', 3, 'bool')); root.add(MyMessage); // In a typical application, you'd load from a .proto file: // import { loadSync } from 'protobufjs'; // import { join } from 'node:path'; // const rootFromFile = loadSync(join(__dirname, 'my_service.proto')); // const MyMessageFromRoot = rootFromFile.lookupType('MyMessage'); // 2. Prepare data to be encoded const payload = { name: 'Jane Doe', id: 123, isActive: true }; // 3. Verify the payload against the schema (optional, but good for debugging) const errMsg = MyMessage.verify(payload); if (errMsg) { throw new Error(`Invalid payload: ${errMsg}`); } // 4. Create a message instance and encode it to a buffer const message = MyMessage.create(payload); const buffer = MyMessage.encode(message).finish(); console.log('Encoded buffer (hex):', buffer.toString('hex')); // 5. Decode the buffer back into a message object const decodedMessage = MyMessage.decode(buffer); console.log('Decoded message:', JSON.stringify(decodedMessage.toJSON())); // Example: decoding a message with missing fields (will use default values) const partialBuffer = MyMessage.encode(MyMessage.create({ name: 'Partial Test' })).finish(); const decodedPartial = MyMessage.decode(partialBuffer); console.log('Decoded partial message (id and isActive default):', JSON.stringify(decodedPartial.toJSON()));
Debug
Known issues
breakingVersion 8.0.0 introduces support for Protocol Buffers Edition 2024. This change may impact parsing and code generation for projects relying on older proto syntax or specific features. Ensure compatibility, especially if migrating from earlier `protobufjs` versions or working with diverse `.proto` definitions.
fix
Review the official Protocol Buffers Edition 2024 documentation for changes. Update your `.proto` files if necessary to adhere to the new edition's specifications, or ensure explicit `syntax` declarations are used. Thoroughly test your application after upgrading.
affects: >=8.0.0
breakingVersions prior to 7.5.5 (specifically 7.5.4 and earlier) were vulnerable to security issues, including prototype pollution via the `__proto__` property in Message constructors and insufficient filtering of invalid characters in type names. This could lead to security exploits.
fix
Upgrade to `protobufjs` v7.5.5 or later immediately. If you are on the `8.x` branch, ensure you are on `v8.0.0` or later, which includes these fixes. Audit your application for any direct manipulation of `__proto__` or reliance on untrusted input for type names.
affects: <7.5.5
gotchaWhen dynamically loading `.proto` files, specifying incorrect or inaccessible paths is a common error. This can be particularly tricky with relative paths in different execution environments (e.g., Node.js vs. browser, or in bundled applications).
fix
Always use robust path resolution, such as `path.join` with `__dirname` or `import.meta.url` for Node.js ESM, to construct absolute paths to your `.proto` files. For browser environments, consider pre-compiling `.proto` files into JSON descriptors or static JavaScript modules.
affects: >=6.0.0
gotcha`protobufjs` offers both `load` (async, Promise-based) and `loadSync` (synchronous) for `.proto` file parsing. Misunderstanding their behavior or mixing them inappropriately can lead to unhandled promises, race conditions, or blocking the main thread.
fix
For most application code, prefer the asynchronous `load` function and handle its Promise with `async/await` to avoid blocking. Reserve `loadSync` for command-line tools, build scripts, or specific initialization scenarios where blocking is acceptable and intended.
affects: >=6.0.0
Errors
Common errors & fixes
Error: ENOENT: no such file or directory, open 'my_service.proto'
The `.proto` file specified in `load` or `loadSync` does not exist at the given path, or the Node.js process lacks read permissions.
fix
Verify that the file path is correct and absolute. Ensure the file is present in the specified location relative to your application's execution context. Use `path.resolve()` or `path.join()` for reliable path construction.
TypeError: Cannot read properties of undefined (reading 'lookupType')
The `Root` object was not successfully loaded (e.g., due to a parsing error in the .proto file), or the provided message type path to `lookupType` does not exist within the loaded schema.
fix
Check the `load` or `loadSync` call for errors. Ensure the full path to your message type (e.g., `my.package.MyMessage`) precisely matches the package and message names defined in your `.proto` file. Log the `root` object to inspect its structure.
Error: .MyMessage#name: string expected
A field in the JavaScript payload object being passed to `create` or `encode` does not match the expected type defined in the .proto schema (e.g., passing a number where a string is expected).
fix
Review the payload object and compare its field types against your `.proto` definition. Use `MyMessage.verify(payload)` before encoding; this method returns an error message if the payload is invalid, aiding in debugging type mismatches.
Upgrade
Version history
8.0.1latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
5 hits · last 30 days
node
4
Amazon
1
Resources
protobufjs — npm install protobufjs · libregistry