protoc-gen-grpc-gateway-ts
is a TypeScript client generator for the grpc-gateway project. It generates idiomatic TypeScript clients that connect the web frontend and golang backend fronted by grpc-gateway.
- Idiomatic Typescript clients and messages.
- Supports both one way and server side streaming gRPC calls.
- POJO request construction guarded by message type definitions, which is way easier compare to
grpc-web
. - No need to use swagger/open api to generate client code for the web.
You will need to install protoc-gen-grpc-gateway-ts
before it could be picked up by the protoc
command. Just run go install github.com/dn3010/protoc-gen-grpc-gateway-ts
protoc-gen-grpc-gateway-ts
should be used along with the protoc
command. A sample invocation looks like the following:
protoc --grpc-gateway-ts_out=ts_import_roots=$(pwd),ts_import_root_aliases=base:. input.proto
As a result the generated file will be input.pb.ts
in the same directory.
Since protoc plugins do not get the import path information as what's specified in protoc -I
, this parameter gives the plugin the same information to figure out where a specific type is coming from so that it can generate import
statement at the top of the generated typescript file. Defaults to $(pwd)
If a project has setup an alias for their import. This parameter can be used to keep up with the project setup. It will print out alias instead of relative path in the import statement. Default to "".
ts_import_roots
& ts_import_root_aliases
are useful when you have setup import alias in your project with the project asset bundler, e.g. Webpack.
protoc-gen-grpc-gateway-ts
generates a shared typescript file with communication functions. These two parameters together will determine where the fetch module file is located. Default to $(pwd)/fetch.pb.ts
To keep the same convention with grpc-gateway
v2 & protojson
. The field name in message generated by this library is in lowerCamelCase by default. If you prefer to make it stick the same with what is defined in the proto file, this option needs to be set to true.
Turn on logging to stderr. Default to false.
Defines the logging levels. Default to info. Valid values are: debug, info, warn, error
Zero-value fields are omitted from the URL query parameter list for GET requests. Therefore for a request payload such as { a: "A", b: "" c: 1, d: 0, e: false }
will become /path/query?a=A&c=1
. A sample implementation is present within this proto file in theintegration_tests
folder. For further explanation please read the following:
- https://developers.google.com/protocol-buffers/docs/proto3#default
- https://github.com/googleapis/googleapis/blob/master/google/api/http.proto
The following shows how to use the generated TypeScript code.
Proto file: counter.proto
// file: counter.proto
message Request {
int32 counter = 1;
}
message Response {
int32 result = 1;
}
service CounterService {
rpc Increase(Request) returns (Response);
rpc Increase10X(Request) returns (stream Response);
}
Run the following command to generate the TypeScript client:
protoc --grpc-gateway-ts_out=. counter.proto
Then a counter.pb.ts
file will be available at the current directory. You can use it like the following example.
import {CounterService} from './counter.pb'
// increase the given number once
async function increase(base: number): Promise<number> {
const resp = await CounterService.Increase({counter: base})
return resp.result
}
// increase the base repeatedly and return all results returned back from server
// the notifier after the request will be called once a result comes back from server streaming
async function increaseRepeatedly(base: number): Promise<number[]> {
let results = []
await CounterService.Increase10X({base}, (resp: Response) => {
result.push(resp.result)
})
return results
}
Copyright 2020 Square, Inc.
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.