• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1Protocol Buffers - Google's data interchange format
2===================================================
3
4[![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/linux-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fubuntu%2Fjavascript%2Fcontinuous) [![Build status](https://storage.googleapis.com/protobuf-kokoro-results/status-badge/macos-javascript.png)](https://fusion.corp.google.com/projectanalysis/current/KOKORO/prod:protobuf%2Fgithub%2Fmaster%2Fmacos%2Fjavascript%2Fcontinuous)
5
6Copyright 2008 Google Inc.
7
8This directory contains the JavaScript Protocol Buffers runtime library.
9
10The library is currently compatible with:
11
121. CommonJS-style imports (eg. `var protos = require('my-protos');`)
132. Closure-style imports (eg. `goog.require('my.package.MyProto');`)
14
15Support for ES6-style imports is not implemented yet.  Browsers can
16be supported by using Browserify, webpack, Closure Compiler, etc. to
17resolve imports at compile time.
18
19To use Protocol Buffers with JavaScript, you need two main components:
20
211. The protobuf runtime library.  You can install this with
22   `npm install google-protobuf`, or use the files in this directory.
23    If npm is not being used, as of 3.3.0, the files needed are located in binary subdirectory;
24    arith.js, constants.js, decoder.js, encoder.js, map.js, message.js, reader.js, utils.js, writer.js
252. The Protocol Compiler `protoc`.  This translates `.proto` files
26   into `.js` files.  The compiler is not currently available via
27   npm, but you can download a pre-built binary
28   [on GitHub](https://github.com/protocolbuffers/protobuf/releases)
29   (look for the `protoc-*.zip` files under **Downloads**).
30
31
32Setup
33=====
34
35First, obtain the Protocol Compiler.  The easiest way is to download
36a pre-built binary from [https://github.com/protocolbuffers/protobuf/releases](https://github.com/protocolbuffers/protobuf/releases).
37
38If you want, you can compile `protoc` from source instead.  To do this
39follow the instructions in [the top-level
40README](https://github.com/protocolbuffers/protobuf/blob/master/src/README.md).
41
42Once you have `protoc` compiled, you can run the tests by typing:
43
44    $ cd js
45    $ npm install
46    $ npm test
47
48    # If your protoc is somewhere else than ../src/protoc, instead do this.
49    # But make sure your protoc is the same version as this (or compatible)!
50    $ PROTOC=/usr/local/bin/protoc npm test
51
52This will run two separate copies of the tests: one that uses
53Closure Compiler style imports and one that uses CommonJS imports.
54You can see all the CommonJS files in `commonjs_out/`.
55If all of these tests pass, you know you have a working setup.
56
57
58Using Protocol Buffers in your own project
59==========================================
60
61To use Protocol Buffers in your own project, you need to integrate
62the Protocol Compiler into your build system.  The details are a
63little different depending on whether you are using Closure imports
64or CommonJS imports:
65
66Closure Imports
67---------------
68
69If you want to use Closure imports, your build should run a command
70like this:
71
72    $ protoc --js_out=library=myproto_libs,binary:. messages.proto base.proto
73
74For Closure imports, `protoc` will generate a single output file
75(`myproto_libs.js` in this example).  The generated file will `goog.provide()`
76all of the types defined in your .proto files.  For example, for the unit
77tests the generated files contain many `goog.provide` statements like:
78
79    goog.provide('proto.google.protobuf.DescriptorProto');
80    goog.provide('proto.google.protobuf.DescriptorProto.ExtensionRange');
81    goog.provide('proto.google.protobuf.DescriptorProto.ReservedRange');
82    goog.provide('proto.google.protobuf.EnumDescriptorProto');
83    goog.provide('proto.google.protobuf.EnumOptions');
84
85The generated code will also `goog.require()` many types in the core library,
86and they will require many types in the Google Closure library.  So make sure
87that your `goog.provide()` / `goog.require()` setup can find all of your
88generated code, the core library `.js` files in this directory, and the
89Google Closure library itself.
90
91Once you've done this, you should be able to import your types with
92statements like:
93
94    goog.require('proto.my.package.MyMessage');
95
96    var message = proto.my.package.MyMessage();
97
98If unfamiliar with Closure or it's compiler, consider reviewing Closure documentation
99https://developers.google.com/closure/library/docs/tutorial
100https://developers.google.com/closure/library/docs/closurebuilder
101https://developers.google.com/closure/library/docs/depswriter
102At a high level, closurebuilder.py can walk dependencies, and compile your code, and all dependencies for Protobuf into a single .js file.  Using depsbuilder.py to generate a dependency file can also be considered for non-production dev environments.
103
104CommonJS imports
105----------------
106
107If you want to use CommonJS imports, your build should run a command
108like this:
109
110    $ protoc --js_out=import_style=commonjs,binary:. messages.proto base.proto
111
112For CommonJS imports, `protoc` will spit out one file per input file
113(so `messages_pb.js` and `base_pb.js` in this example).  The generated
114code will depend on the core runtime, which should be in a file called
115`google-protobuf.js`.  If you are installing from `npm`, this file should
116already be built and available.  If you are running from GitHub, you need
117to build it first by running:
118
119    $ gulp dist
120
121Once you've done this, you should be able to import your types with
122statements like:
123
124    var messages = require('./messages_pb');
125
126    var message = new messages.MyMessage();
127
128The `--js_out` flag
129-------------------
130
131The syntax of the `--js_out` flag is:
132
133    --js_out=[OPTIONS:]output_dir
134
135Where `OPTIONS` are separated by commas.  Options are either `opt=val` or
136just `opt` (for options that don't take a value).  The available options
137are specified and documented in the `GeneratorOptions` struct in
138[src/google/protobuf/compiler/js/js_generator.h](https://github.com/protocolbuffers/protobuf/blob/master/src/google/protobuf/compiler/js/js_generator.h#L53).
139
140Some examples:
141
142- `--js_out=library=myprotos_lib.js,binary:.`: this contains the options
143  `library=myprotos.lib.js` and `binary` and outputs to the current directory.
144  The `import_style` option is left to the default, which is `closure`.
145- `--js_out=import_style=commonjs,binary:protos`: this contains the options
146  `import_style=commonjs` and `binary` and outputs to the directory `protos`.
147  `import_style=commonjs_strict` doesn't expose the output on the global scope.
148
149API
150===
151
152The API is not well-documented yet.  Here is a quick example to give you an
153idea of how the library generally works:
154
155    var message = new MyMessage();
156
157    message.setName("John Doe");
158    message.setAge(25);
159    message.setPhoneNumbers(["800-555-1212", "800-555-0000"]);
160
161    // Serializes to a UInt8Array.
162    var bytes = message.serializeBinary();
163
164    var message2 = MyMessage.deserializeBinary(bytes);
165
166For more examples, see the tests.  You can also look at the generated code
167to see what methods are defined for your generated messages.
168