gRPC-Web Client Runtime Library
npm install grpc-webgRPC-Web provides a Javascript library that lets browser clients access a gRPC
service. You can find out much more about gRPC in its own
website.
gRPC-Web is now Generally Available, and considered stable enough for production use.
gRPC-Web clients connect to gRPC services via a special gateway proxy: the
current version of the library uses Envoy by
default, in which gRPC-Web support is built-in.
In the future, we expect gRPC-Web to be supported in language-specific Web
frameworks, such as Python, Java, and Node. See the
roadmap doc.
This example is using the echo.proto file from the
Echo Example.
1. Add grpc-web as a dependency using npm.
``sh`
$ npm i grpc-web
2. Download protoc and the protoc-gen-grpc-web protoc plugin.
You can download the protoc binary from the official
protocolbuffers
release page.
You can download the protoc-gen-grpc-web protoc plugin from our Github
release page.
Make sure they are both executable and are discoverable from your PATH.
3. Generate your proto messages and the service client stub classes with
protoc and the protoc-gen-grpc-web plugin. You can set theimport_style=commonjs option for both --js_out and --grpc-web_out.
`sh`
$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:generated \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:generated
4. Start using your generated client!
`js
const {EchoServiceClient} = require('./generated/echo_grpc_web_pb.js');
const {EchoRequest} = require('./generated/echo_pb.js');
const client = new EchoServiceClient('localhost:8080');
const request = new EchoRequest();
request.setMessage('Hello World!');
const metadata = {'custom-header-1': 'value1'};
client.echo(request, metadata, (err, response) => {
// ...
});
`
To complete the example, you need to run a proxy that understands the
gRPC-Web protocol
between your browser client and your gRPC service. The default proxy currently
is Envoy. Please visit our
Github repo for more information.
Here's a quick way to get started!
`sh`
$ git clone https://github.com/grpc/grpc-web
$ cd grpc-web
$ docker-compose up node-server envoy commonjs-client
Open a browser tab, and go to:
``
http://localhost:8081/echotest.html
The grpc-web module can now be imported as a TypeScript module. This is
currently an experimental feature. Any feedback welcome!
When using the protoc-gen-grpc-web protoc plugin, mentioned above, pass in
either:
- import_style=commonjs+dts: existing CommonJS style stub + .d.ts typingsimport_style=typescript
- : full TypeScript output
`ts
import * as grpcWeb from 'grpc-web';
import {EchoServiceClient} from './echo_grpc_web_pb';
import {EchoRequest, EchoResponse} from './echo_pb';
const echoService = new EchoServiceClient('http://localhost:8080', null, null);
const request = new EchoRequest();
request.setMessage('Hello World!');
const call = echoService.echo(request, {'custom-header-1': 'value1'},
(err: grpcWeb.RpcError, response: EchoResponse) => {
console.log(response.getMessage());
});
call.on('status', (status: grpcWeb.Status) => {
// ...
});
`
See a full TypeScript example
here.
Pre-requisites:
- protocprotoc-gen-grpc-web
- plugin
`sh``
$ npm test