{"id":10960,"library":"google-protobuf","title":"Google Protocol Buffers for JavaScript","description":"Protocol Buffers for JavaScript provides the runtime library for Google's efficient, language-agnostic, and extensible mechanism for serializing structured data. The current stable version is 4.0.2, with releases generally tied to upstream `protoc` compiler updates and critical bug fixes, focusing on maintaining compatibility. This package primarily serves as the runtime component, which is internally consumed by JavaScript files generated from `.proto` definitions using the `protoc` compiler and its `protoc-gen-js` plugin. It explicitly supports CommonJS-style and Closure-style imports for the generated code, but direct ES6 module support for these generated `.js` files is not yet implemented, often necessitating build tools like Webpack or Browserify for seamless browser integration. A key differentiator is its deep integration with the broader Protocol Buffers ecosystem, offering a robust and standardized solution for defining and exchanging structured data across different programming languages in JavaScript and Node.js applications.","status":"maintenance","version":"4.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/protocolbuffers/protobuf-javascript","tags":["javascript"],"install":[{"cmd":"npm install google-protobuf","lang":"bash","label":"npm"},{"cmd":"yarn add google-protobuf","lang":"bash","label":"yarn"},{"cmd":"pnpm add google-protobuf","lang":"bash","label":"pnpm"}],"dependencies":[],"imports":[{"note":"For user-defined messages generated with `protoc --js_out=import_style=commonjs,binary:.`. Generated files are CommonJS, not ESM.","wrong":"import { MyMessage } from './my_proto_pb';","symbol":"MyMessage","correct":"const { MyMessage } = require('./my_proto_pb');"},{"note":"For well-known types like Timestamp. Paths are internal and follow CommonJS module resolution.","wrong":"import { Timestamp } => from 'google-protobuf/google/protobuf/timestamp_pb';","symbol":"Timestamp","correct":"const { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb');"},{"note":"Accessing core `jspb` utilities like `Message`, `BinaryReader`, `BinaryWriter`. Primarily for advanced use, typically internal to generated code. Follows CommonJS.","wrong":"import jspb from 'google-protobuf/google/protobuf/jspb/jspb.js';","symbol":"jspb","correct":"const jspb = require('google-protobuf/google/protobuf/jspb/jspb.js');"}],"quickstart":{"code":"/*\nFirst, ensure you have the `protoc` compiler installed and on your PATH.\nDownload a pre-built binary from https://github.com/protocolbuffers/protobuf/releases\n\nThen install the necessary npm packages:\nnpm install google-protobuf @protocolbuffers/protoc-gen-js\n\nCreate a file named `example.proto`:\n*/\n// example.proto\n/*\nsyntax = \"proto3\";\npackage mypackage;\n\nmessage MyMessage {\n  string name = 1;\n  int32 id = 2;\n  repeated string tags = 3;\n}\n*/\n\n/*\nCompile your .proto file using protoc:\nprotoc --js_out=import_style=commonjs,binary:. example.proto \\\n       --plugin=protoc-gen-js=$(npm root)/@protocolbuffers/protoc-gen-js/cli.js\n\nThis will generate `example_pb.js`.\nNow, run this JavaScript code (e.g., `node quickstart.js`):\n*/\n\nconst { MyMessage } = require('./example_pb'); // Import the generated message class\nconst { Timestamp } = require('google-protobuf/google/protobuf/timestamp_pb'); // Import a well-known type\n\n// Create a new instance of MyMessage\nconst message = new MyMessage();\nmessage.setName('Hello Protobuf World');\nmessage.setId(42);\nmessage.addTags('example');\nmessage.addTags('typescript');\n\nconsole.log('Original Message:', message.toObject());\n\n// Serialize the message to a binary buffer\nconst binaryData = message.serializeBinary();\nconsole.log('Serialized Binary Data:', binaryData);\n\n// Deserialize the message from the binary buffer\nconst deserializedMessage = MyMessage.deserializeBinary(binaryData);\n\nconsole.log('Deserialized Message Name:', deserializedMessage.getName());\nconsole.log('Deserialized Message ID:', deserializedMessage.getId());\nconsole.log('Deserialized Message Tags:', deserializedMessage.getTagsList());\n\n// Demonstrate using a Timestamp well-known type\nconst now = new Date();\nconst timestamp = new Timestamp();\ntimestamp.fromDate(now); // Convert a JavaScript Date object to a Protobuf Timestamp\n\nconsole.log('Current Timestamp (Protobuf format):', timestamp.toObject());\n","lang":"javascript","description":"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."},"warnings":[{"fix":"Review 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`.","message":"Version 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`.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use 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.","message":"The 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.","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Ensure 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.","message":"The `@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.","severity":"gotcha","affected_versions":"4.0.0 - 4.0.1"},{"fix":"The 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.","message":"Early 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`.","severity":"gotcha","affected_versions":"4.0.2 (initial release)"},{"fix":"Factor this into project planning, especially for enterprise use cases requiring rapid support. Rely more on community resources or consider contributing fixes for critical issues.","message":"The 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.","severity":"gotcha","affected_versions":">=4.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Ensure 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.","cause":"Attempting to `require()` a generated `.proto` file (e.g., `my_proto_pb.js`) that has not been created, or the path is incorrect.","error":"Error: Cannot find module './my_proto_pb'"},{"fix":"Download 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.","cause":"The Protocol Compiler (`protoc`) is not installed or not accessible in your system's PATH.","error":"protoc: command not found"},{"fix":"Install 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`).","cause":"The `protoc-gen-js` plugin, which translates `.proto` files to JavaScript, is not installed or `protoc` cannot find it.","error":"plugin was not found: protoc-gen-js"}],"ecosystem":"npm"}