Protoc Plugin for generating TypeScript Declarations
This repository contains a protoc plugin that generates TypeScript declarations
(.d.ts
files) that match the JavaScript output of protoc --js_out=import_style=commonjs,binary
. This plugin can
also output service definitions as both .js
and .d.ts
files in the structure required by grpc-web, and as .d.ts
files in the structure required by grpc-node.
This plugin is tested and written using TypeScript 2.7.
As a prerequisite, download or install protoc
(the protocol buffer compiler) for your platform from the github releases page or via a package manager (ie: brew, apt).
For the latest stable version of the ts-protoc-gen plugin:
npm install ts-protoc-gen
For our latest build straight from master:
npm install ts-protoc-gen@next
Instructions for using ts-protoc-gen within a bazel build environment
Prerequisites:
- Setup rules_nodejs in your project
Then, include the following in your WORKSPACE
:
load("@bazel_tools//tools/build_defs/repo:http.bzl", "http_archive")
# NOTE: Setup rules_nodejs
http_archive(
name = "ts_protoc_gen",
# NOTE: Update these values to the latest version
sha256 = "355bd8e7a3d4889a3fb222366ac3427229acc968455670378f8ffe1b4bfc5a95",
strip_prefix = "ts-protoc-gen-14d69f6203c291f15017a8c0abbb1d4b52b00b64",
urls = ["https://github.com/improbable-eng/ts-protoc-gen/archive/14d69f6203c291f15017a8c0abbb1d4b52b00b64.zip"],
)
load("@ts_protoc_gen//:defs.bzl", "typescript_proto_dependencies")
typescript_proto_dependencies()
Also make sure you have the following in your package.json
:
{
"dependencies": {
"google-protobuf": "^3.6.1",
"@improbable-eng/grpc-web": "0.8.0",
"browser-headers": "^0.4.1"
},
"devDependencies": {
"@bazel/karma": "0.27.8",
"@bazel/typescript": "^0.27.7",
"@types/google-protobuf": "^3.2.7",
"typescript": "^3.1.1"
}
}
Run
yarn install
to generate theyarn.lock
file.
Finally, in your BUILD.bazel
:
load("@ts_protoc_gen//:defs.bzl", "typescript_proto_library")
proto_library(
name = "test_proto",
srcs = [
"test.proto",
],
)
typescript_proto_library(
name = "test_ts_proto",
proto = ":test_proto",
)
You can use the test_ts_proto
as a dep
in other ts_library
targets. However, you will need to
include google-protobuf
, @improbable-eng/grpc-web
, and browser-headers
at runtime yourself. See
//test/bazel:pizza_service_proto_test_suite
for an example.
If you'd like to get code completion working for the generated protos in your IDE, add the following to your tsconfig.json
:
{
"compilerOptions": {
"baseUrl": ".",
"paths": {
# Replace <workspace-name> with the name of your workspace
"<workspace-name>/*": [
"*", # Enables absolute paths for src files in your project
"bazel-bin/*" # Enables referencing generate protos with absolute paths
]
}
}
}
NOTE: This has only been tested in IntelliJ with the bazel plugin
Contributions are welcome! Please refer to CONTRIBUTING.md for more information.
As mentioned above, this plugin for protoc
serves two purposes:
- Generating TypeScript Definitions for CommonJS modules generated by protoc
- Generating gRPC service clients for use with grpc-web or grpc-node.
By default, protoc will generate ES5 code when the --js_out
flag is used (see javascript compiler documentation). You have the choice of two module syntaxes, CommonJS or closure. This plugin (ts-protoc-gen
) can be used to generate Typescript definition files (.d.ts
) to provide type hints for CommonJS modules only.
To generate TypeScript definitions you must first configure protoc
to use this plugin and then specify where you want the TypeScript definitions to be written to using the --ts_out
flag.
# Path to this plugin
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"
# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"
protoc \
--plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
--js_out="import_style=commonjs,binary:${OUT_DIR}" \
--ts_out="${OUT_DIR}" \
users.proto base.proto
In the above example, the generated
folder will contain both .js
and .d.ts
files which you can reference in your TypeScript project to get full type completion and make use of ES6-style import statements, eg:
import { MyMessage } from "../generated/users_pb";
const msg = new MyMessage();
msg.setName("John Doe");
gRPC is a framework that enables client and server applications to communicate transparently, and makes it easier to build connected systems.
grpc-web is a comparability layer on both the server and client-side which allows gRPC to function natively in modern web-browsers.
To generate client-side service stubs from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the service=grpc-web
param to the --ts_out
flag, eg:
# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"
# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"
protoc \
--plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
--js_out="import_style=commonjs,binary:${OUT_DIR}" \
--ts_out="service=grpc-web:${OUT_DIR}" \
users.proto base.proto
The generated
folder will now contain both pb_service.js
and pb_service.d.ts
files which you can reference in your TypeScript project to make RPCs.
Note Note that these modules require a CommonJS environment. If you intend to consume these stubs in a browser environment you will need to use a module bundler such as webpack.
Note Both js
and d.ts
service files will be generated regardless of whether there are service definitions in the proto files.
import {
UserServiceClient,
GetUserRequest
} from "../generated/users_pb_service";
const client = new UserServiceClient("https://my.grpc/server");
const req = new GetUserRequest();
req.setUsername("johndoe");
client.getUser(req, (err, user) => {
/* ... */
});
This plugin can generate .d.ts
files for gRPC service definitions as required by grpc-node.
To generate these declaration files from your protobuf files you must configure ts-protoc-gen to emit service definitions by passing the service=grpc-node
param to the --ts_out
flag, eg:
# Path to this plugin, Note this must be an abolsute path on Windows (see #15)
PROTOC_GEN_TS_PATH="./node_modules/.bin/protoc-gen-ts"
# Path to the grpc_node_plugin
PROTOC_GEN_GRPC_PATH="./node_modules/.bin/grpc_tools_node_protoc_plugin"
# Directory to write generated code to (.js and .d.ts files)
OUT_DIR="./generated"
protoc \
--plugin="protoc-gen-ts=${PROTOC_GEN_TS_PATH}" \
--plugin=protoc-gen-grpc=${PROTOC_GEN_GRPC_PATH} \
--js_out="import_style=commonjs,binary:${OUT_DIR}" \
--ts_out="service=grpc-node:${OUT_DIR}" \
--grpc_out="${OUT_DIR}" \
users.proto base.proto
The generated
folder will now contain both _grpc_pb.js
and _grpc_pb.d.ts
files which you can reference in your TypeScript project to make RPCs.
Note This plugin does not generate the _grpc_pb.js
files itself; those are generated by the protoc-gen-grpc plugin. This plugin only generates the _grpc_pb.d.ts
files.
- Example output -- Code generated by
ts-protoc-gen
. - Packaging the output as a node module -- Example of how to use the generated code as a dependendecy of another module.
By default the google-protobuf library will use the JavaScript number type to store 64bit float and integer values; this can lead to overflow problems as you exceed JavaScript's Number.MAX_VALUE
. To work around this, you should consider using the jstype
annotation on any 64bit fields, ie:
message Example {
uint64 bigInt = 1 [jstype = JS_STRING];
}