Protocol Buffers Compiler (protoc) plugin for TypeScript and gRPC-Web.
TypeScript Python Shell JavaScript
Clone or download
Jonny Reeves
Jonny Reeves Bumped to v0.7.7-pre
Latest commit 50bb30c Jul 18, 2018
Permalink
Failed to load latest commit information.
.github Create stale.yml (#68) May 21, 2018
bin Fix bazel building (#71) May 23, 2018
examples/generated/proto Remove legacy generated artificats. Jul 18, 2018
proto Add Custom Bazel rule (#84) Jun 10, 2018
src add debug to ServiceClientOptions (#90) Jun 13, 2018
test Fix broken integration test after cleaning up generated examples protos Jul 18, 2018
.gitattributes Move generated protos to examples and check them in (#55) May 20, 2018
.gitignore Download protoc when generating protos (#80) May 29, 2018
.npmignore Download protoc when generating protos (#80) May 29, 2018
.nvmrc Upgrade to node 8 (#41) Mar 25, 2018
.travis.yml Fixes #97 (#98) Jul 18, 2018
BUILD.bazel Add Custom Bazel rule (#84) Jun 10, 2018
CHANGELOG.md Bumped to v0.7.7-pre Jul 18, 2018
CODE_OF_CONDUCT.md Add CONTRIBUTING.md & CODE_OF_CONDUCT.md (#54) Apr 3, 2018
CONTRIBUTING.md Add CONTRIBUTING.md & CODE_OF_CONDUCT.md (#54) Apr 3, 2018
LICENSE.txt TypeScript + Tests Mar 25, 2017
README.md README update: add git repo for ts_protoc_gen and remove rule duplica… Jul 18, 2018
WORKSPACE Add Custom Bazel rule (#84) Jun 10, 2018
defs.bzl Add Custom Bazel rule (#84) Jun 10, 2018
generate.sh Add Custom Bazel rule (#84) Jun 10, 2018
package-lock.json Bumped to v0.7.7-pre Jul 18, 2018
package.json Bumped to v0.7.7-pre Jul 18, 2018
release.sh No need to perform the NPM publish as Travis does this. May 26, 2018
travis-ci-build.sh Fix build script permissions May 25, 2018
tsconfig.json TypeScript + Tests Mar 25, 2017
tslint.json Fix and Restructure Tests (#69) May 23, 2018

README.md

Master Build NPM NPM Apache 2.0 License

ts-protoc-gen

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.

This plugin is tested and written using TypeScript 2.7.

Installation

npm

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

bazel

Include the following in your WORKSPACE:

git_repository(
    name = "io_bazel_rules_go",
    commit = "6bee898391a42971289a7989c0f459ab5a4a84dd",  # master as of May 10th, 2018
    remote = "https://github.com/bazelbuild/rules_go.git",
    )
load("@io_bazel_rules_go//go:def.bzl", "go_rules_dependencies", "go_register_toolchains")
go_rules_dependencies()
go_register_toolchains()

http_archive(
  name = "io_bazel_rules_webtesting",
  strip_prefix = "rules_webtesting-master",
  urls = [
    "https://github.com/bazelbuild/rules_webtesting/archive/master.tar.gz",
  ],
)
load("@io_bazel_rules_webtesting//web:repositories.bzl", "browser_repositories", "web_test_repositories")
web_test_repositories()

git_repository(
  name = "build_bazel_rules_nodejs",
  remote = "https://github.com/bazelbuild/rules_nodejs.git",
  commit = "d334fd8e2274fb939cf447106dced97472534e80",
)
load("@build_bazel_rules_nodejs//:defs.bzl", "node_repositories")
node_repositories(package_json = ["//:package.json"])

git_repository(
    name = "ts_protoc_gen",
    remote = "https://github.com/improbable-eng/ts-protoc-gen.git",
    commit = "05c52b843edf9420be3a9549d01352dfeff76a5e",
)

load("@ts_protoc_gen//:defs.bzl", "typescript_proto_dependencies")
typescript_proto_dependencies()

git_repository(
  name = "build_bazel_rules_typescript",
  remote = "https://github.com/bazelbuild/rules_typescript.git",
  commit = "3488d4fb89c6a02d79875d217d1029182fbcd797",
)
load("@build_bazel_rules_typescript//:defs.bzl", "ts_setup_workspace")
ts_setup_workspace()

Now in your BUILD.bazel:

load("@ts_protoc_gen//:defs.bzl", "typescript_proto_library")

filegroup(
  name = "proto_files",
  srcs = glob(["*.proto"]),
)

proto_library(
  name = "proto",
  srcs = [
    ":proto_files",
  ],
)

typescript_proto_library(
  name = "generate",
  proto = ":proto",
)

Contributing

Contributions are welcome! Please refer to CONTRIBUTING.md for more information.

Usage

As mentioned above, this plugin for protoc serves two purposes:

  1. Generating TypeScript Definitions for CommonJS modules generated by protoc
  2. Generating gRPC Service Stubs for use with grpc-web.

Generating TypeScript Definitions for CommonJS modules generated by protoc

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");

Generating gRPC Service Stubs for use with grpc-web

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=true param to the --ts_out flag, eg:

# 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="service=true:${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 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) => { /* ... */ });

Examples

For a sample of the generated protos and service definitions, see examples.

To generate the examples from protos, please run ./generate.sh