A set of tools to simplify working with protobuf.js, protoc and its plugins.
Why: generating code from proto files is a rather tricky thing because various utilities (protoc itself, pbjs, etc) have a lot of various options and it is also necessary to set proper include and plugins paths. Moreover some well known proto files, such as datetime.proto, openapiv2.proto and others are the part of other repositories and packages, so in order to use them, you have to copy them to your repository every time. As a result, you ought to perform a lot of routine every time.
What: grpc-tools was created to simplify code generation and provide default include paths with well known proto files.
npm i @byndyusoft/grpc-tools
We consider that a code generation is a part of build process, which can be started locally by developer and remotely by CI/CD. So there is no need to store artifacts of the proto files building in a repos since our package is helping easily automate this process. We recommend the following usage scenario:
- install package to the
buildscript in the
package.json, which describe code generation process using the commands provided by our package
- execute code generation by running
npm run build
Short description of the commands provided by our package are listed below.
Generates js files from proto files via
pbjs from protobuf.js providing default include path. Code generation can be started by command
$ js-protoc-gen -r greeter -t static-module -w commonjs --no-verify -o ./tests/generated/server/greeter_pb.js ./tests/protos/greeter.proto
Generates swagger json from proto files via
protoc-gen-swagger from grpc-gateway providing default include path. Code generation can be started by command
$ swagger-protoc-gen --swagger_opt=json_names_for_fields=true --swagger_out=logtostderr=true:./tests/generated/server/ -I ./tests/protos/ greeter.proto
A detailed overview on how to contribute can be found in the contributing guide.
Make sure you have installed all of the following prerequisites on your development machine:
- Git - Download & Install Git. OSX and Linux machines typically have this already installed.
- Node.js (version 10 or higher) - Download & Install Node.js and the npm package manager.
General folders layout
- configs for Visual Studio Code.
- scripts for the CI build process
- repository submodules
src/bin- tools entry points.
src/include- well known proto files, copied from other repositories, which are generated by command
npm run build:copy. Folder is created automatically during the build process and was excluded from repository.
*- implementation of the service.
- tests for the result of code generation.
Package development lifecycle
- Declare new tool in the
- Implement tool entry point in
- Implement tool logic in
- Add or addapt unit-tests (prefer before and simultaneously with coding)
- Add or change the documentation as needed
- Open pull request in the correct branch. Target the project's
src/protos- files on which code generation can be tested.
tests/generated— artifacts of the proto files compilation, which are generated by command
npm run build. Folder is created automatically during the build process and was excluded from repository.
tests/\*.test.js— unit test cases
Tests can be run using the following commands.
$ npm i $ npm link $ npm run build $ npm t