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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
MyMessage
✓ const { MyMessage } = require('./my_proto_pb');
✗ import { MyMessage } from './my_proto_pb';
For user-defined messages generated with `protoc --js_out=import_style=commonjs,binary:.`. Generated files are CommonJS, not ESM.
Timestamp
✓ const { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb');
✗ import { Timestamp } => from 'google-protobuf/google/protobuf/timestamp_pb';
For well-known types like Timestamp. Paths are internal and follow CommonJS module resolution.
jspb
✓ const jspb = require('google-protobuf/google/protobuf/jspb/jspb.js');
✗ import jspb from 'google-protobuf/google/protobuf/jspb/jspb.js';
Accessing core `jspb` utilities like `Message`, `BinaryReader`, `BinaryWriter`. Primarily for advanced use, typically internal to generated code. Follows CommonJS.
This quickstart demonstrates how to define a Protocol Buffer message, compile it using `protoc` and `protoc-gen-js`, and then use the generated JavaScript classes to create, serialize, and deserialize messages, including a well-known type like Timestamp.
/*
First, ensure you have the `protoc` compiler installed and on your PATH.
Download a pre-built binary from https://github.com/protocolbuffers/protobuf/releases
Then install the necessary npm packages:
npm install google-protobuf @protocolbuffers/protoc-gen-js
Create a file named `example.proto`:
*/
// example.proto
/*
syntax = "proto3";
package mypackage;
message MyMessage {
string name = 1;
int32 id = 2;
repeated string tags = 3;
}
*/
/*
Compile your .proto file using protoc:
protoc --js_out=import_style=commonjs,binary:. example.proto \
--plugin=protoc-gen-js=$(npm root)/@protocolbuffers/protoc-gen-js/cli.js
This will generate `example_pb.js`.
Now, run this JavaScript code (e.g., `node quickstart.js`):
*/
const { MyMessage } = require('./example_pb'); // Import the generated message class
const { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb'); // Import a well-known type
// Create a new instance of MyMessage
const message = new MyMessage();
message.setName('Hello Protobuf World');
message.setId(42);
message.addTags('example');
message.addTags('typescript');
console.log('Original Message:', message.toObject());
// Serialize the message to a binary buffer
const binaryData = message.serializeBinary();
console.log('Serialized Binary Data:', binaryData);
// Deserialize the message from the binary buffer
const deserializedMessage = MyMessage.deserializeBinary(binaryData);
console.log('Deserialized Message Name:', deserializedMessage.getName());
console.log('Deserialized Message ID:', deserializedMessage.getId());
console.log('Deserialized Message Tags:', deserializedMessage.getTagsList());
// Demonstrate using a Timestamp well-known type
const now = new Date();
const timestamp = new Timestamp();
timestamp.fromDate(now); // Convert a JavaScript Date object to a Protobuf Timestamp
console.log('Current Timestamp (Protobuf format):', timestamp.toObject());
Debug
Known issues
breakingVersion 4.0.0 introduced significant breaking changes, including changes to binary proto serialization/deserialization, enabling Protobuf Editions 2023, fixes for JSPB binary UTF-8 decoding (validated by default), and limiting global resolution to `globalThis`.fixReview the full changelog for v4.0.0 and update code paths affected by serialization, UTF-8 handling, and global scope assumptions. Re-generate `.js` files with a compatible `protoc` and `protoc-gen-js`.
affects: >=4.0.0
gotchaThe generated JavaScript files (e.g., `_pb.js`) do not natively support ES6-style `import` statements. They are designed for CommonJS `require()` or Closure `goog.require()`. Attempting to use `import` directly for generated files will result in module resolution errors.fixUse CommonJS `require()` for generated `.js` files. If targeting browser environments or requiring ESM, utilize build tools like Webpack, Rollup, or Browserify to transpile/bundle your code, ensuring CommonJS modules are correctly resolved.
affects: >=3.0.0
gotchaThe `@protocolbuffers/protoc-gen-js` plugin was temporarily hardcoded to download version 4.0.0, lacking support for Editions 2024, leading to compilation issues for newer `.proto` definitions. This was fixed in `google-protobuf` v4.0.2.fixEnsure you are using `google-protobuf` and `@protocolbuffers/protoc-gen-js` version 4.0.2 or later to correctly support Protobuf Editions 2024 and ensure the correct plugin version is downloaded.
affects: 4.0.0 - 4.0.1
gotchaEarly releases of v4.0.2 had issues with macOS and Windows binaries for `protoc-gen-js` being double-zipped, causing download script failures within `@protocolbuffers/protoc-gen-js`.fixThe binaries were re-uploaded. If encountering issues with `protoc-gen-js` on macOS/Windows, ensure your `npm cache` is cleared and reinstall `@protocolbuffers/protoc-gen-js` to get the corrected archives, or manually download the correct `protoc` binary if needed.
affects: 4.0.2 (initial release)
gotchaThe project explicitly states that it has 'minimal support for this open source project', with limited staffing to answer questions beyond triage. This indicates slower response times for issues and feature requests.fixFactor this into project planning, especially for enterprise use cases requiring rapid support. Rely more on community resources or consider contributing fixes for critical issues.
affects: >=4.0.0
Errors
Common errors & fixes
Error: Cannot find module './my_proto_pb'
Attempting to `require()` a generated `.proto` file (e.g., `my_proto_pb.js`) that has not been created, or the path is incorrect.
fixEnsure you have successfully compiled your `.proto` file using `protoc` with the correct output directory (e.g., `protoc --js_out=import_style=commonjs,binary:. my_proto.proto`). Verify the path in your `require()` statement matches the generated file's location.
protoc: command not found
The Protocol Compiler (`protoc`) is not installed or not accessible in your system's PATH.
fixDownload and install `protoc` from the official Protocol Buffers GitHub releases page (https://github.com/protocolbuffers/protobuf/releases) and ensure its directory is added to your system's PATH environment variable.
plugin was not found: protoc-gen-js
The `protoc-gen-js` plugin, which translates `.proto` files to JavaScript, is not installed or `protoc` cannot find it.
fixInstall the plugin via npm (`npm install @protocolbuffers/protoc-gen-js`) and ensure you pass the `--plugin` argument to `protoc`, specifying the full path to `cli.js` (e.g., `--plugin=protoc-gen-js=$(npm root)/@protocolbuffers/protoc-gen-js/cli.js`).
Audit
Dependencies
No dependency data recorded yet.