Repository files navigation

Copyright 2008 Google Inc.

This directory contains the JavaScript Protocol Buffers runtime library.

The library is currently compatible with:

1. CommonJS-style imports (eg.var protos = require('my-protos');)
2. Closure-style imports (eg.goog.require('my.package.MyProto');)

Support for ES6-style imports is not implemented yet. Browsers canbe supported by using Browserify, webpack, Closure Compiler, etc. toresolve imports at compile time.

To use Protocol Buffers with JavaScript, you need two main components:

1. The protobuf runtime library. You can install this withnpm install google-protobuf, or use the files in this directory.If npm is not being used, as of 3.3.0, the files needed are located in binary subdirectory;arith.js, constants.js, decoder.js, encoder.js, map.js, message.js, reader.js, utils.js, writer.js
2. The Protocol Compilerprotoc. This translates.proto filesinto.js files. The compiler is not currently available vianpm, but you can download a pre-built binaryon GitHub(look for theprotoc-*.zip files underDownloads).

This project is currently in a working state.

Support Status

We currently do not have staffing for more than minimal support for this opensource project. We will answer questions and triage any issues.

Contributing

Contributions should preserve existing behavior where possible. Currentcustomers rely on applications continuing to work across minor version upgrades.We encourage small targeted contributions. Thanks!

First, obtain the Protocol Compiler. The easiest way is to downloada pre-built binary fromhttps://github.com/protocolbuffers/protobuf/releases.

If you want, you can compileprotoc from source instead. To do thisfollow the instructions inthe top-levelREADME.

Once you haveprotoc compiled, you can run the tests provided along with ourproject to examine whether it can run successfully. In order to do this, youshould download the Protocol Buffer source code from the release page with thelink above. Then extract the source code and navigate to the folder namedjscontaining apackage.json file and a series of test files. In this folder, youcan run the commands below to run the tests automatically.

$ npm install$ PROTOC_INC=/usr/include/google/protobuf npm test

PROTOC_INC specifies the protobuf include path. By default, we useprotoclocated fromPATH. Optionally, you can use thePROTOC enviroment variable tospecify an alternativeprotoc.

This will run two separate copies of the tests: one that usesClosure Compiler style imports and one that uses CommonJS imports.You can see all the CommonJS files incommonjs_out/.If all of these tests pass, you know you have a working setup.

To use Protocol Buffers in your own project, you need to integratethe Protocol Compiler into your build system. The details are alittle different depending on whether you are using Closure importsor CommonJS imports:

If you want to use Closure imports, your build should run a commandlike this:

$ protoc --js_out=library=myproto_libs,binary:. messages.proto base.proto

For Closure imports,protoc will generate a single output file(myproto_libs.js in this example). The generated file willgoog.provide()all of the types defined in your .proto files. For example, for the unittests the generated files contain manygoog.provide statements like:

goog.provide('proto.google.protobuf.DescriptorProto');goog.provide('proto.google.protobuf.DescriptorProto.ExtensionRange');goog.provide('proto.google.protobuf.DescriptorProto.ReservedRange');goog.provide('proto.google.protobuf.EnumDescriptorProto');goog.provide('proto.google.protobuf.EnumOptions');

The generated code will alsogoog.require() many types in the core library,and they will require many types in the Google Closure library. So make surethat yourgoog.provide() /goog.require() setup can find all of yourgenerated code, the core library.js files in this directory, and theGoogle Closure library itself.

Once you've done this, you should be able to import your types withstatements like:

goog.require('proto.my.package.MyMessage');varmessage=proto.my.package.MyMessage();

If unfamiliar with Closure or its compiler, consider reviewingClosure documentation.

If you want to use CommonJS imports, your build should run a commandlike this:

$ protoc --js_out=import_style=commonjs,binary:. messages.proto base.proto

For CommonJS imports,protoc will spit out one file per input file(somessages_pb.js andbase_pb.js in this example). The generatedcode will depend on the core runtime, which should be in a file calledgoogle-protobuf.js. If you are installing fromnpm, this file shouldalready be built and available. If you are running from GitHub, you needto build it first by running:

$ gulp dist

Once you've done this, you should be able to import your types withstatements like:

varmessages=require('./messages_pb');varmessage=newmessages.MyMessage();

The syntax of the--js_out flag is:

--js_out=[OPTIONS:]output_dir

WhereOPTIONS are separated by commas. Options are eitheropt=val orjustopt (for options that don't take a value). The available optionsare specified and documented in theGeneratorOptions struct ingenerator/js_generator.h.

Some examples:

• --js_out=library=myprotos_lib.js,binary:.: this contains the optionslibrary=myprotos.lib.js andbinary and outputs to the current directory.Theimport_style option is left to the default, which isclosure.
• --js_out=import_style=commonjs,binary:protos: this contains the optionsimport_style=commonjs andbinary and outputs to the directoryprotos.import_style=commonjs_strict doesn't expose the output on the global scope.

The API is not well-documented yet. Here is a quick example to give you anidea of how the library generally works:

varmessage=newMyMessage();message.setName("John Doe");message.setAge(25);message.setPhoneNumbers(["800-555-1212","800-555-0000"]);// Serializes to a UInt8Array.varbytes=message.serializeBinary();varmessage2=MyMessage.deserializeBinary(bytes);

For more examples, see the tests. You can also look at the generated codeto see what methods are defined for your generated messages.