Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

grpc-web

grpc396kApache-2.01.5.0TypeScript support: included

gRPC-Web Client Runtime Library

readme

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.

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.

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.

  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.RpcError, 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.4.2

  • #1289 Expose getName() in MethodDescriptor and fix TS definitions.
  • #1230 GrpcWebClientReadableStream: keep falsy data @pro-wh

1.4.1

  • #1286 Fix duplicate dot in enum name (when "package" is specified)

1.4.0

Major Features

  • #1249 Use Zig to build aarch64 binaries @hronro
  • #1203 Github Actions (workflows) for building protoc-gen-grpc-web plugins

Other Changes

  • #1279 Fixes the status codes ordering in typescript definitions @chandraaditya
  • #1278 Fix Enum with module in generated TS interface.
  • #1254 Remove Trailing Slashes from Hostname @jkjk822
  • #1252 Fix Zig setup step in CI @hronro
  • #1231 Add version flag and version info in generated code @meling
  • #1225 Improve error message & Internal code sync
  • #1222 Update envoy version to 1.22 (with config updates) @tomk9
  • #1211 Upgrade protobuf and grpc deps @aapeliv
  • #1199 Revert "Expose MethodDescriptor's public methods"

1.3.1

  • #1184 Correctly support proto3 optional fields in commonjs+dts .d.ts output @mattnathan
  • #1173 Update envoy version to 1.20
  • #1172 Fix issue where no RPC is issued when deadline is specified.
  • #1167 Fix missing TypeScript return type for serverStreaming calls. @lukasmoellerch
  • #1166 Add missing exports from RpcError and add test.
  • #1164 Add missing class exports @tinrab
  • #1160 Expose MethodDescriptor's public methods @tomferreira

1.3.0

Major Features

  • #1139 Improve error type with RpcError & internal code sync (contributor: @TomiBelan)
    • (experimental) Typescript users need to update type references from Error -> RpcError

Other Changes

  • #1140 Improve RpcError.code typing & internal code sync (contributor: @richieforeman)
  • #1138 Remove Bazel in Javascript toolchain
  • #1137 Revamp Closure JsUnit tests runtime and optimize test/build flows.
  • #1115 Bump Bazel version -> 4.1.0 and Protobuf version -> 3.17.3
  • #1107 Allow for custom install prefix @06kellyjac
  • #1063 Also set timeout on HTTP request if deadline for grpc call is set @Yannic
  • #1004 Bump closure library version to v20201102
  • #1002 Bump Envoy version to 1.16.1
  • #998 Fix GrpcWebClientBaseOptions types in index.d.ts @acalvo
  • #971 Add grpc.web.ClientOptions to better document options and add type res... @jennnnny
  • #969 Fix non-determinism in code generator
  • #941 Fix Protobuf .d.ts typings for .proto files without package @Yannic

1.2.1

  • #910 Add test to show how to access metadata in interceptor
  • #903 Add error handling to a few error conditions
  • #886 Add missing types definitions
  • #885 Bump Envoy to 1.15.0
  • #884 Update protoc plugin to support Proto3 optional
  • #882 Add @interface MethodDescroptorInterface @Jennnnny
  • #880 Update Bazel to 3.3.1 @Yannic
  • #874 Add removeListener and missing metadata event types @danielthank
  • #872 [bazel] Introduce grpc_web_toolchain @Yannic
  • #871 [generator] Refactor dependency management @Yannic
  • #869 Add scripts to run interop-tests on grpc-web Java connector

1.2.0

Major Features

  • #847 Allow multiple .on() callbacks and fix issue with non-OK status

Other Changes

  • #859 Fix envoy.yaml deprecated fields @dmaixner
  • #858 Refactor error handling in grpcwebclientbase
  • #857 Migrate to ES6 classes
  • #852 Update to use @grpc/grpc-js node package, and update helloworld exampl...
  • #851 Add a ThenableCall base class for the promise-based unaryCall function @Jennnnny
  • #844 Fix code generator bug and add tests
  • #833 Add proper author attribution to release notes / changelog
  • #827 Splitting callback based client and Promise based client into multiple... @Jennnnny
  • #822 use explicit envoy release tag @xsbchen
  • #821 Experimental Feature: Add ES6 import style @Yannic
  • #738 Avoid double slash in url when client hostname has tailing slash @hanabi1224

1.1.0

Major Features

  • #785 grpc-web interceptors implementation @Jennnnny
  • #772 Add interop test spec and interop tests

Other Changes

  • #818 All java connector interop tests are passing now
  • #804 Fix a bug in test: callback not properly intercepted
  • #801 Trying to speed up tests
  • #797 Split basic tests with interop tests
  • #780 Add missing separator to imports from external files @tomiaijo
  • #777 Add .on(metadata,...) callback to distinguish initial metadata
  • #764 [generator] Move options parsing into dedicated class @Yannic
  • #761 Update generic client @Jennnnny
  • #756 Add eval test for TypeScript generated code
  • #752 Disable static checkers on generated js files @IagoLast
  • #747 Enable builder pattern in Typescript protobuf messages. @Orphis
  • #746 Generate Promise based overloads for unary calls in Typescript @Orphis
  • #745 [bazel] Update rules_closure + fix linter warnings @Yannic
  • #734 Allow GrpcWebStreamParser to accept Uint8Array @travikk
  • #723 Update bazel version
  • #720 Fix grpcwebproxy interop
  • #716 allow_origin is deprecated in latest envoy server @noconnor
  • #695 Fix issue 632 (double execution of callback) @hfinger
  • #692 Do not hardcode CXX to g++

1.0.7

  • #671 Add metadata to error callback
  • #668 Remove stream_body.proto
  • #665 Add config for Bazel CI @Yannic
  • #663 nginx example Expose-Headers add Grpc-Message,Grpc-Status @zsluedem
  • #657 Ensure that the end callback is called @vbfox
  • #655 Use closure compiler from npm in build.js @vbfox
  • #654 Ignore MacOS .DS_Store files @vbfox
  • #652 Fix error callback
  • #644 Add CallOptions class @Jennnnny
  • #641 Add/update GOVERNANCE.md and CONTRIBUTING.md
  • #635 Fix generated code return type, and remove unused var
  • #628 Added API for simple unary call @Jennnnny
  • #621 Fix output directory name when using import_style=typescript @asv
  • #619 Return specific grpc status code on http error @harmangakhal
  • #618 Generate method descriptors into multiple files @Jennnnny
  • #617 Remove enabled deprecated field @gsalisi
  • #615 Add support in code generator for printing only method descriptors @Jennnnny
  • #608 Fix status and error callbacks

1.0.6

  • #604 Add option to set withCredentials to true
  • #603 Adding some groundwork for generic client @Jennnnny
  • #600 Add generated code eval test
  • #599 fix wrong package name of input type @lqs
  • #593 Fix: Helloworld Example - Enabled Deprecation @gary-lo

1.0.5

1.0.4

1.0.3

1.0.2

1.0.1

  • #354 [dts] Generate PromiseClient type definitions in d.ts file @at-ishikawa
  • #352 Add a max grpc timeout to the echo example. @mjduijn
  • #348 Fix output dts about 'repeated' for --grpc-web_out=import_style=common... @rybbchao
  • #345 update typescript generation to work in strict mode @henriiik
  • #330 Use official rules_closure repository @Yannic

1.0.0

  • #314 Add a unit test for proto with no package
  • #313 Show how deadline can be set
  • #311 Document how to prevent Envoy to timeout streaming @mitar
  • #310 Correctly generate code if package name is empty @mitar
  • #304 Add a simple Hello World Guide
  • #303 Error code should be number
  • #276 Fix plugin compile error
  • #272 Fix cpp warnings

0.4.0

  • #263 Make "Quick" start quicker
  • #258 Experimental Typescript support
  • #257 Fix bug with button in example

0.3.0

  • #249 Various fixes to codegen plugin
  • #247 Add generated code unit test
  • #240 webpack demo
  • #239 Expose response metadata for unary calls
  • #219 Add bazel rule closure_grpc_web_library @Yannic
  • #217 Added multiple proxies interoperability

0.2.0

  • #212 Added commonjs-example Dockerfile
  • #211 commonjs support with import_style option @zaucy
  • #210 grpcweb npm runtime module @zaucy
  • #209 Add bazel integration and tests
  • #206 Surface underlying XHR errors better
  • #185 Support for proto files without packages @zaucy