grpc-web

gRPC-Web Client Runtime Library

gRPC-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.

The current release is a Beta release, and we expect to announce General-Availability by Oct. 2018.

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.

Quick Start

This example is using the echo.proto file from the Echo Example.

1. Add grpc-web as a dependency using npm.

$ npm i grpc-web

1. 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.

For example, in MacOS, you can do:

$ sudo mv ~/Downloads/protoc-gen-grpc-web-1.0.4-darwin-x86_64 \
  /usr/local/bin/protoc-gen-grpc-web
$ chmod +x /usr/local/bin/protoc-gen-grpc-web

1. Generate your proto messages and the service client stub classes with protoc and the protoc-gen-grpc-web plugin. You can set the import_style=commonjs option for both --js_out and --grpc-web_out.

$ protoc -I=$DIR echo.proto \
--js_out=import_style=commonjs:generated \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:generated

1. Start using your generated client!

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) => {
  // ...
});

What's Next

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!

$ 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

TypeScript Support

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 typings
• import_style=typescript: full TypeScript output

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.Error, response: EchoResponse) => {
    console.log(response.getMessage());
  });
call.on('status', (status: grpcWeb.Status) => {
  // ...
});

See a full TypeScript example here.

Run Tests

Pre-requisites:

• protoc
• protoc-gen-grpc-web plugin

$ npm test

Changelog

1.0.5

• #582 Ensure credentials are not undefined in typescript @Globegitter
• #579 Uppercase enum keys in TypeScript definitions @benfoxbotica
• #578 Fix depset issues with/upgrade to Bazel 0.27.1 @factuno-db
• #567 Introducing MethodDescriptor @Jennnnny
• #559 Adding new fields to MethodInfo @Jennnnny
• #556 Add fix for deadline of strings, NaN, Infinity and -Infinity @CatEars
• #546 Changes to deserializeBinary API
• #540 Method Derserializer should take Uint8Array @pnegahdar
• #519 remove duplicated has$field$ method for oneof @yangjian
• #512 Make client args credentials and options optional @jonahbron