gRPC Web ·

A JavaScript implementation ofgRPCfor browser clients. For more information, including aquick start,see thegRPC-web documentation.

gRPC-web clients connect to gRPC services via a special proxy; by default, gRPC-web usesEnvoy.

In the future, we expect gRPC-web to be supported in language-specific web frameworks for languages such as Python, Java, and Node. For details, see the roadmap.

Streaming Support

gRPC-web currently supports 2 RPC modes:

• Unary RPCs (example)
• Server-side Streaming RPCs (example) (NOTE: Only whengrpcwebtextmode is used.)

Client-side and Bi-directional streaming is not currently supported (seestreaming roadmap).

Quick Start

Eager to get started? Try theHello World example.From this example, you'll learn how to do the following:

• Define your service using protocol buffers
• Implement a simple gRPC Service using NodeJS
• Configure the Envoy proxy
• Generate protobuf message classes and client service stub for the client
• Compile all the JS dependencies into a static library that can be consumed by the browser easily

Advanced Demo: Browser Echo App

You can also try to run a more advanced Echo app from the browser with a streaming example.

From the repo root directory:

$ docker-compose pull prereqs node-server envoy commonjs-client
$ docker-compose up node-server envoy commonjs-client

Open a browser tab, and visithttp://localhost:8081/echotest.html.

To shutdown:docker-compose down.

Runtime Library

The gRPC-web runtime library is available atnpm:

$ npm i grpc-web

Code Generator Plugins

(Prerequisite) 1. Protobuf (protoc)

If you don't already haveprotoc installed, download it first fromhereand install it on your PATH.

If you use Homebrew (on macOS), you could run:

brew install protobuf

(Prerequisite) 2. Protobuf-javascript (protoc-gen-js)

If you don't haveprotoc-gen-jsinstalled, download it fromprotocolbuffers/protobuf-javascriptand install it on your PATH.

Or, use thethird-partyNPM installer:

npm install -g protoc-gen-js

3. Install gRPC-Web Code Generator

You can download theprotoc-gen-grpc-webprotoc plugin from our releasepage:

Make sure all executables are discoverable from your PATH.

For example, on MacOS, you can do:

sudo mv protoc-gen-grpc-web-1.5.0-darwin-aarch64 \
/usr/local/bin/protoc-gen-grpc-web

chmod +x /usr/local/bin/protoc-gen-grpc-web

(Optional) 4. Verify Installations

You can optionally verify the plugins works follwoing ourHello world example:

cdnet/grpc/gateway/examples/helloworld

protoc -I=. helloworld.proto \
--js_out=import_style=commonjs:. \
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:.

After the command runs successfully, you should now see two new files generated in the current directory. By running:

ls -1 *_pb.js

Installation is successful if you see the following 2 files:

• helloworld_pb.js# Generated byprotoc-gen-jsplugin
• helloworld_grpc_web_pb.js- Generated by gRPC-Web plugin

Client Configuration Options

Typically, you will run the following command to generate the proto messages and the service client stub from your.protodefinitions:

protoc -I=$DIRecho.proto \
--js_out=import_style=commonjs:$OUT_DIR\
--grpc-web_out=import_style=commonjs,mode=grpcwebtext:$OUT_DIR

You can then use Browserify, Webpack, Closure Compiler, etc. to resolve imports at compile time.

Import Style

import_style=closure:The default generated code has Closuregoog.require() import style.

import_style=commonjs:The CommonJSstylerequire()is also supported.

import_style=commonjs+dts:(Experimental) In addition to above, a.d.ts typings file will also be generated for the protobuf messages and service stub.

import_style=typescript:(Experimental) The service stub will be generated in TypeScript. SeeTypeScript Supportbelow for information on how to generate TypeScript files.

Note:Thecommonjs+dtsandtypescriptstyles are only supported by --grpc-web_out=import_style=...,not by--js_out=import_style=....

Wire Format Mode

For more information about the gRPC-web wire format, see the specification.

mode=grpcwebtext:The default generated code sends the payload in the grpc-web-textformat.

• Content-type: application/grpc-web-text
• Payload are base64-encoded.
• Both unary and server streaming calls are supported.

mode=grpcweb:A binary protobuf format is also supported.

• Content-type: application/grpc-web+proto
• Payload are in the binary protobuf format.
• Only unary calls are supported.

How It Works

Let's take a look at how gRPC-web works with a simple example. You can find out how to build, run and explore the example yourself in Build and Run the Echo Example.

1. Define your service

The first step when creating any gRPC service is to define it. Like all gRPC services, gRPC-web uses protocol buffersto define its RPC service methods and their message request and response types.

messageEchoRequest{
stringmessage=1;
}

...

serviceEchoService{
rpcEcho(EchoRequest)returns(EchoResponse);

rpcServerStreamingEcho(ServerStreamingEchoRequest)
returns(streamServerStreamingEchoResponse);
}

2. Run the server and proxy

Next you need to have a gRPC server that implements the service interface and a gateway proxy that allows the client to connect to the server. Our example builds a simple Node gRPC backend server and the Envoy proxy.

For the Echo service: see the service implementations.

For the Envoy proxy: see the config yaml file.

3. Write your JS client

Once the server and gateway are up and running, you can start making gRPC calls from the browser!

Create your client:

varechoService=newproto.mypackage.EchoServiceClient(
'http://localhost:8080');

Make a unary RPC call:

varrequest=newproto.mypackage.EchoRequest();
request.setMessage(msg);
varmetadata={'custom-header-1':'value1'};
echoService.echo(request,metadata,function(err,response){
if(err){
console.log(err.code);
console.log(err.message);
}else{
console.log(response.getMessage());
}
});

Server-side streaming:

varstream=echoService.serverStreamingEcho(streamRequest,metadata);
stream.on('data',function(response){
console.log(response.getMessage());
});
stream.on('status',function(status){
console.log(status.code);
console.log(status.details);
console.log(status.metadata);
});
stream.on('end',function(end){
// stream end signal
});

// to close the stream
stream.cancel()

For an in-depth tutorial, seethis page.

Setting Deadline

You can set a deadline for your RPC by setting adeadlineheader. The value should be a Unix timestamp, in milliseconds.

vardeadline=newDate();
deadline.setSeconds(deadline.getSeconds()+1);

client.sayHelloAfterDelay(request,{deadline:deadline.getTime().toString()},
(err,response)=>{
// err will be populated if the RPC exceeds the deadline
...
});

TypeScript Support

Thegrpc-webmodule can now be imported as a TypeScript module. This is currently an experimental feature. Any feedback welcome!

When using theprotoc-gen-grpc-webprotoc plugin, mentioned above, pass in either:

• import_style=commonjs+dts:existing CommonJS style stub +.d.tstypings
• import_style=typescript:full TypeScript output

Donotuseimport_style=typescriptfor--js_out,it will silently be ignored. Instead you should use--js_out=import_style=commonjs,or --js_out=import_style=commonjs,binaryif you are usingmode=grpcweb.The --js_outplugin will generate JavaScript code (echo_pb.js), and the -grpc-web_outplugin will generate a TypeScript definition file for it (echo_pb.d.ts). This is a temporary hack until the--js_outsupports TypeScript itself.

For example, this is the command you should use to generate TypeScript code using the binary wire format

protoc -I=$DIRecho.proto \
--js_out=import_style=commonjs,binary:$OUT_DIR\
--grpc-web_out=import_style=typescript,mode=grpcweb:$OUT_DIR

It will generate the following files:

• EchoServiceClientPb.ts- Generated by--grpc-web_out,contains the TypeScript gRPC-web code.
• echo_pb.js- Generated by--js_out,contains the JavaScript Protobuf code.
• echo_pb.d.ts- Generated by--grpc-web_out,contains TypeScript definitions forecho_pb.js.

Using Callbacks

import*asgrpcWebfrom'grpc-web';
import{EchoServiceClient}from'./EchoServiceClientPb';
import{EchoRequest,EchoResponse}from'./echo_pb';

constechoService=newEchoServiceClient('http://localhost:8080',null,null);

constrequest=newEchoRequest();
request.setMessage('Hello World!');

constcall=echoService.echo(request,{'custom-header-1':'value1'},
(err:grpcWeb.RpcError,response:EchoResponse)=>{
console.log(response.getMessage());
});
call.on('status',(status:grpcWeb.Status)=>{
//...
});

(Seeherefull list of possible.on(...)callbacks)

(Option) Using Promises (Limited features)

NOTE:It is not possible to access the.on(...)callbacks (e.g. formetadataandstatus) when Promise is used.

// Create a Promise client instead
constechoService=newEchoServicePromiseClient('http://localhost:8080',null,null);

...(sameasabove)

this.echoService.echo(request,{'custom-header-1':'value1'})
.then((response:EchoResponse)=>{
console.log(`Received response:${response.getMessage()}`);
}).catch((err:grpcWeb.RpcError)=>{
console.log(`Received error:${err.code},${err.message}`);
});

For the full TypeScript example, see ts-example/client.tswith theinstructionsto run.

Custom Interceptors

Custom interceptors can be implemented and chained, which could be useful for features like auth, retries, etc.

There are 2 types of interceptors (interfaces):

• UnaryInterceptor(doc,example) - Intercept Unary RPCs; can only be used with Promise clients.
• StreamInterceptor(doc,example) - More versatile; can be used with regular clients.

For more details, seethis blog post.

Ecosystem

Proxy Interoperability

Multiple proxies support the gRPC-web protocol.

1. The currentdefault proxyisEnvoy,which supports gRPC-web out of the box.

   $ docker-compose up -d node-server envoy commonjs-client

2. You can also try thegRPC-web Go proxy.

   $ docker-compose up -d node-server grpcwebproxy binary-client

3. ApacheAPISIXhas also added grpc-web support, and more details can be foundhere.

4. Nginxhas a grpc-web module (doc,announcement)), and seems to work with simple configs, according to userfeedback.

Server Frameworks with gRPC-Web support

• Armeria (JVM)
• Tonic (Rust)

Web Frameworks Compatibility

• Vite- See thisdemo app,as well as thiscomment.