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).

protobuf.js is a pure JavaScript implementation with TypeScript support for node and the browser. It's super easy to use, blazingly fast and works out of the box on .proto files!

Recommended read: Changes in protobuf.js 6.0

Features

Optimized for performance
Excellent browser support
Managed TypeScript definitions
Elaborate API documentation
Convenient CLI utilities
Seamless browserify integration

Usage
How to include protobuf.js in your project.
Examples
A few examples to get you started.
Documentation
A list of available documentation resources.
Command line
How to use the command line utility.
Performance
A few internals and a benchmark on performance.
Compatibility
Notes on compatibility regarding browsers and optional libraries.
Building
How to build the library and its components yourself.

Usage

node.js

$> npm install protobufjs

var protobuf = require("protobufjs");

Browsers

Development:

<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.js"></script>

Production:

<script src="//cdn.rawgit.com/dcodeIO/protobuf.js/6.X.X/dist/protobuf.min.js"></script>

NOTE: Remember to replace the version tag with the exact release your project depends upon.

Or download the library.

The protobuf namespace will always be available globally / also supports AMD loaders.

Examples

Using .proto files

// awesome.proto
package awesomepackage;
syntax = "proto3";

message AwesomeMessage {
    string awesome_field = 1; // becomes awesomeField
}

protobuf.load("awesome.proto", function(err, root) {
    if (err) throw err;

    // Obtain a message type
    var AwesomeMessage = root.lookup("awesomepackage.AwesomeMessage");

    // Create a new message
    var message = AwesomeMessage.create({ awesomeField: "AwesomeString" });

    // Encode a message
    var buffer = AwesomeMessage.encode(message).finish();
    // ... do something with buffer

    // Or, encode a plain object
    var buffer = AwesomeMessage.encode({ awesomeField: "AwesomeString" }).finish();
    // ... do something with buffer

    // Decode a buffer
    var message = AwesomeMessage.decode(buffer);
    // ... do something with message

    // If your application uses length-delimited buffers, there is also encodeDelimited and decodeDelimited.
});

You can also use promises by omitting the callback:

protobuf.load("awesome.proto")
    .then(function(root) {
       ...
    });

Using reflection only

...
var Root  = protobuf.Root,
    Type  = protobuf.Type,
    Field = protobuf.Field;

var AwesomeMessage = new Type("AwesomeMessage").add(new Field("awesomeField", 1, "string"));

var root = new Root().define("awesomepackage").add(AwesomeMessage);

// Continue at "Create a new message" above
...

Using custom classes

...

function AwesomeMessage(properties) {
    protobuf.Message.call(this, properties);
}
protobuf.Class.create(root.lookup("awesomepackage.AwesomeMessage") /* or use reflection */, AwesomeMessage);

var message = new AwesomeMessage({ awesomeField: "AwesomeString" });

// Continue at "Encode a message" above

Custom classes are automatically populated with static encode, encodeDelimited, decode, decodeDelimited and verify methods and reference their reflected type via the $type property. Note that there are no methods (just $type) on instances by default as method names might conflict with field names.

Using the Reader/Writer interface directly

While only useful for the adventurous cherishing an aversion to generated static code, it's also possible to use the Reader/Writer interface directly depending just on the minimal runtime (basic example).

Easy ways to obtain example code snippets are either setting protobuf.util.codegen.verbose = true while watching the magic as it happens, or simply inspecting generated static code.

Using services

// greeter.proto
syntax = "proto3";

service Greeter {
    rpc SayHello (HelloRequest) returns (HelloReply) {}
}

message HelloRequest {
    string name = 1;
}

message HelloReply {
    string message = 1;
}

...
var Greeter = root.lookup("Greeter");
var greeter = Greeter.create(rpcImpl, false, false); // rpcImpl (see below), requestDelimited?, responseDelimited?

greeter.sayHello({ name: 'you' }, function(err, response) {
    console.log('Greeting:', response.message);
});

To make this work, all you have to do is provide an rpcImpl, which is an asynchronous function that takes the reflected service method, the binary HelloRequest and a node-style callback as its parameters. For example:

function rpcImpl(method, requestData, callback) {
    // perform the request using an HTTP request or a WebSocket for example
    var responseData = ...;
    // and call the callback with the binary response afterwards:
    callback(null, responseData);
}

There is also an example for streaming RPC.

Usage with TypeScript

import * as protobuf from "protobufjs";
import * as Long from "long"; // optional
...

Additional configuration might be necessary when not utilizing node, i.e. reference protobuf.js.d.ts and long.js.d.ts.

Documentation

Google's Developer Guide
protobuf.js API Documentation and CHANGELOG
Frequently asked questions on our wiki
More questions and answers on StackOverflow

Command line

The pbjs command line utility can be used to bundle and translate between .proto and .json files.

Consolidates imports and converts between file formats.

  -t, --target    Specifies the target format. Also accepts a path to require a custom target.

                  json          JSON representation
                  json-module   JSON representation as a module
                  proto2        Protocol Buffers, Version 2
                  proto3        Protocol Buffers, Version 3
                  static        Static code without reflection
                  static-module Static code without reflection as a module

  -p, --path      Adds a directory to the include path.

  -o, --out       Saves to a file instead of writing to stdout.

  Module targets only:

  -w, --wrap      Specifies the wrapper to use. Also accepts a path to require a custom wrapper.

                  default   Default wrapper supporting both CommonJS and AMD
                  commonjs  CommonJS wrapper
                  amd       AMD wrapper
                  es6       ES6 wrapper

  -r, --root      Specifies an alternative protobuf.roots name.

  -l, --lint      Linter configuration. Defaults to protobuf.js-compatible rules:

                  eslint-disable block-scoped-var, no-redeclare, no-control-regex

  Proto sources only:

  --keep-case     Keeps field casing instead of converting to camel case.

  Static targets only:

  --no-create     Does not generate create functions used for reflection compatibility.
  --no-encode     Does not generate encode functions.
  --no-decode     Does not generate decode functions.
  --no-verify     Does not generate verify functions.
  --no-convert    Does not generate convert functions like from/toObject
  --no-delimited  Does not generate delimited encode/decode functions.
  --no-beautify   Does not beautify generated code.
  --no-comments   Does not output any JSDoc comments.

usage: pbjs [options] file1.proto file2.json ...  (or)  other | pbjs [options] -

For production environments it is recommended to bundle all your .proto files to a single .json file, which reduces the number of network requests and parser invocations required:

$> pbjs -t json file1.proto file2.proto > bundle.json

Now, either include this file in your final bundle:

var root = protobuf.Root.fromJSON(require("./bundle.json"));

or load it the usual way:

protobuf.load("bundle.json", function(err, root) {
    ...
});

ProTip! Documenting your .proto files with /** ... */-blocks translates to generated static code.

Generating TypeScript definitions from static modules

Likewise, the pbts command line utility can be used to generate TypeScript definitions from pbjs-generated static modules.

Generates TypeScript definitions from annotated JavaScript files.

  -n, --name      Wraps everything in a module of the specified name.

  -o, --out       Saves to a file instead of writing to stdout.

  -m, --main      Whether building the main library without any imports.

  -g, --global    Name of the global object in browser environments, if any.

  --no-comments   Does not output any JSDoc comments.

usage: pbts [options] file1.js file2.js ...  (or)  other | pbts [options] -

Using pbjs and pbts programmatically

Both utilities can be used programmatically by providing command line arguments and a callback to their respective main functions:

var pbjs = require("protobufjs/cli/pbjs");

pbjs.main([ "--target", "json-module", "path/to/myproto.proto" ], function(err, output) {
    if (err)
        throw err;
    // do something with output
});

Descriptors vs. static modules

While .proto and JSON files require the full library (about 17.5kb gzipped), pretty much all code but the relatively short descriptors is shared and all features including reflection and the parser are available.

Static code, on the other hand, requires just the minimal runtime (about 5.5kb gzipped), but generates additional, albeit editable, source code without any reflection features.

There is no difference performance-wise as the code generated statically is pretty much the same as generated at runtime.

Additionally, JSON modules can be used with TypeScript definitions generated for their static counterparts as long as the following conditions are met:

Use SomeMessage.create(...) instead of new SomeMessage(...) (reflection does not provide such a constructor).
Types, services and enums must start with an uppercase letter to become available as properties of the reflected types as well.
When using a TypeScript definition with custom code, resolveAll() must be called once on the root instance to populate these additional properties (JSON modules do this automatically).

Performance

The package includes a benchmark that tries to compare performance to native JSON as far as this is possible. On an i7-2600K running node 6.9.1 it yields:

benchmarking encoding performance ...

Type.encode to buffer x 521,803 ops/sec ±0.84% (88 runs sampled)
JSON.stringify to string x 300,362 ops/sec ±1.11% (86 runs sampled)
JSON.stringify to buffer x 169,413 ops/sec ±1.49% (86 runs sampled)

      Type.encode to buffer was fastest
   JSON.stringify to string was 42.6% slower
   JSON.stringify to buffer was 67.7% slower

benchmarking decoding performance ...

Type.decode from buffer x 1,325,308 ops/sec ±1.46% (88 runs sampled)
JSON.parse from string x 283,907 ops/sec ±1.39% (86 runs sampled)
JSON.parse from buffer x 255,372 ops/sec ±1.28% (88 runs sampled)

    Type.decode from buffer was fastest
     JSON.parse from string was 78.6% slower
     JSON.parse from buffer was 80.7% slower

benchmarking combined performance ...

Type to/from buffer x 269,719 ops/sec ±0.87% (91 runs sampled)
JSON to/from string x 122,878 ops/sec ±1.59% (87 runs sampled)
JSON to/from buffer x 89,310 ops/sec ±1.01% (88 runs sampled)

        Type to/from buffer was fastest
        JSON to/from string was 54.8% slower
        JSON to/from buffer was 66.9% slower

benchmarking verifying performance ...

Type.verify x 5,857,856 ops/sec ±0.82% (91 runs sampled)

Note that JSON is a native binding nowadays and as such is about as fast as it possibly can get. So, how can protobuf.js be faster?

The benchmark is somewhat flawed.
Reader and writer interfaces configure themselves according to the environment to eliminate redundant conditionals.
Node-specific reader and writer subclasses benefit from node's buffer binding.
Reflection has built-in code generation that builds type-specific encoders, decoders and verifiers at runtime.
Encoders and decoders do not implicitly call verify on messages to avoid unnecessary overhead where messages are already known to be valid. It's up to the user to call verify where necessary.
Quite a bit of V8-specific profiling is accountable for everything else.

You can also run the benchmark ...

$> npm run bench

and the profiler yourself (the latter requires a recent version of node):

$> npm run prof <encode|decode|encode-browser|decode-browser> [iterations=10000000]

Note that as of this writing, the benchmark suite performs significantly slower on node 7.2.0 compared to 6.9.1 because moths.

Compatibility

Because the internals of this package do not rely on google/protobuf/descriptor.proto, options are parsed and presented literally.
If typed arrays are not supported by the environment, plain arrays will be used instead.
Support for pre-ES5 environments (except IE8) can be achieved by using a polyfill.
Support for Content Security Policy-restricted environments (like Chrome extensions without unsafe-eval) can be achieved by generating and using static code instead.
If you need a proper way to work with 64 bit values (uint64, int64 etc.), you can install long.js alongside this library. All 64 bit numbers will then be returned as a Long instance instead of a possibly unsafe JavaScript number (see).

Building

To build the library or its components yourself, clone it from GitHub and install the development dependencies:

$> git clone https://github.com/dcodeIO/protobuf.js.git
$> cd protobuf.js
$> npm install

Building the development and production versions with their respective source maps to dist/:

$> npm run build

Building the documentation to docs/:

$> npm run docs

Building the TypeScript definition to index.d.ts:

$> npm run types

Browserify integration

By default, protobuf.js integrates into your browserify build-process without requiring any optional modules. Hence:

If you need int64 support, explicitly require the long module somewhere in your project. It will be excluded otherwise.
If you have any special requirements, there is the bundler as a reference.

License: BSD 3-Clause License

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

README.md

README.md

Features

Contents

Usage

node.js

Browsers

Examples

Using .proto files

Using reflection only

Using custom classes

Using the Reader/Writer interface directly

Using services

Usage with TypeScript

Documentation

Command line

Generating TypeScript definitions from static modules

Using pbjs and pbts programmatically

Descriptors vs. static modules

Performance

Compatibility

Building

Browserify integration

Files

README.md

Latest commit

History

README.md

File metadata and controls

Features

Contents

Usage

node.js

Browsers

Examples

Using .proto files

Using reflection only

Using custom classes

Using the Reader/Writer interface directly

Using services

Usage with TypeScript

Documentation

Command line

Generating TypeScript definitions from static modules

Using pbjs and pbts programmatically

Descriptors vs. static modules

Performance

Compatibility

Building

Browserify integration