grpc-web

grpc-web is a JavaScript implementation of gRPC for browser clients, maintained under the grpc/grpc-web repository. Because browsers cannot open raw HTTP/2 gRPC connections, gRPC-web clients talk to gRPC services through a special proxy; Envoy is the default proxy, and the project also documents interoperability with the gRPC-web Go proxy, Apache APISIX, and Nginx's gRPC module. The project ships two main pieces. First, a runtime library published on npm as `grpc-web`, which is now written entirely in TypeScript and therefore provides first-class type safety, zero runtime dependencies, and built-in type definitions. Second, a protoc plugin, `protoc-gen-grpc-web`, that generates client service stubs from `.proto` definitions. Generation typically pairs the standard `--js_out` plugin (for protobuf message classes) with `--grpc-web_out` (for the service stub), and can be bundled with Browserify, Webpack, or Closure Compiler. Supported RPC modes are unary calls and server-side streaming. Server-side streaming is only available in `grpcwebtext` wire format mode, where payloads are base64-encoded and sent with `Content-Type: application/grpc-web-text`. A binary mode, `grpcweb`, uses `Content-Type: application/grpc-web+proto` with binary protobuf payloads but supports only unary calls. Client-side and bidirectional streaming are not currently supported. Code generation offers several import styles: `closure` (the default, using `goog.require()`), `commonjs` (using `require()`), `commonjs+dts` (CommonJS stubs plus a `.d.ts` typings file), and `typescript` (full TypeScript output). The `commonjs+dts` and `typescript` styles are only supported by `--grpc-web_out`, not by `--js_out`. The README includes a concrete example of generating TypeScript code with the binary wire format, which produces a TypeScript service client, a JavaScript protobuf module, and a matching `.d.ts` definition file. Client usage is straightforward: instantiate a service client with a proxy URL, build a request message, and call the RPC with optional metadata and a callback. Server-side streaming returns a stream object with `data`, `status`, and `end` events, plus a `cancel()` method. A deadline can be set by passing a `deadline` header containing a Unix timestamp in milliseconds. Two client styles are available: callback-based clients and Promise-based clients, though the Promise variant cannot access `.on(...)` callbacks for metadata and status. Custom interceptors can be implemented and chained for features such as authentication and retries. Two interceptor types exist: `UnaryInterceptor`, which intercepts unary RPCs and can only be used with Promise clients, and `StreamInterceptor`, which is more versatile and works with regular clients. The repository includes a Hello World example that walks through defining a service with protocol buffers, implementing a Node.js gRPC service, configuring the Envoy proxy, generating protobuf classes and client stubs, and compiling JS dependencies into a static library. A more advanced Echo demo can be run with Docker Compose and exposes a browser page for testing streaming. The README also points to ecosystem integrations, including Armeria (JVM) and Tonic (Rust) server frameworks with gRPC-web support, and a Vite compatibility demo. A roadmap document outlines future work, including language-specific web framework support for Python, Java, and Node.