gRPC-Web — gRPC for Browser Clients

Introduction

gRPC-Web is a JavaScript client library that brings gRPC to the browser. Since browsers cannot directly open HTTP/2 frames, gRPC-Web uses a translation layer (typically an Envoy proxy) to bridge browser HTTP requests to backend gRPC services. This lets frontend and backend teams share the same Protobuf service definitions and type-safe contracts.

What gRPC-Web Does

• Enables browser JavaScript and TypeScript to call gRPC services using generated client stubs
• Supports unary RPCs and server-side streaming from the browser
• Generates type-safe client code from .proto service definitions
• Works with Envoy, Nginx, or any proxy that implements the gRPC-Web protocol translation
• Provides both grpc-web-text (base64) and grpc-web (binary) wire formats

Architecture Overview

gRPC-Web clients send HTTP/1.1 or HTTP/2 requests with a special Content-Type header (application/grpc-web). A proxy (Envoy is the reference implementation) translates these into standard gRPC HTTP/2 frames and forwards them to the backend service. Responses follow the reverse path. The client library handles Protobuf serialization and deserialization using the google-protobuf JavaScript runtime.

Self-Hosting & Configuration

• Install the protoc-gen-grpc-web plugin alongside the standard protoc compiler
• Configure Envoy with an envoy.filters.http.grpc_web filter to enable protocol translation
• Set CORS headers in the proxy to allow cross-origin requests from your frontend domain
• Use the generated client classes in any bundler setup (Webpack, Vite, esbuild)
• Enable TLS on the proxy for production deployments with gRPC-Web over HTTPS

Key Features

• Shares .proto definitions between frontend and backend for a single source of truth
• Type-safe generated clients prevent mismatched request and response shapes
• Server-side streaming delivers real-time updates to the browser via chunked responses
• Interceptor API allows adding authentication headers, logging, and retry logic
• Compatible with any gRPC backend regardless of language (Go, Java, Python, C++)

Comparison with Similar Tools

• REST + JSON — ubiquitous but lacks code generation and strict type contracts
• tRPC — TypeScript-native RPC for full-stack TS apps, no Protobuf or proxy needed
• ConnectRPC — modern alternative that supports gRPC, gRPC-Web, and Connect protocols natively without a proxy
• GraphQL — flexible query language with its own schema system, better for ad-hoc queries than RPC-style calls

FAQ

Q: Do I need Envoy to use gRPC-Web? A: Envoy is the reference proxy, but alternatives like grpcwebproxy (Go) or Nginx with the grpc_web module also work. ConnectRPC servers can handle gRPC-Web natively without a proxy.

Q: Does gRPC-Web support bidirectional streaming? A: No. Browsers do not support HTTP/2 bidirectional streaming. gRPC-Web supports unary calls and server-side streaming only.

Q: Can I use gRPC-Web with TypeScript? A: Yes. The code generator produces TypeScript definitions, and the grpc-web package includes type declarations.

Q: What is the overhead compared to native gRPC? A: The proxy adds a small latency hop. The grpc-web-text format uses base64 encoding which increases payload size by about 33%, while the binary format avoids this.

Sources

• https://github.com/grpc/grpc-web
• https://grpc.io/docs/platforms/web/