# gRPC-Web — gRPC for Browser Clients

> A JavaScript client library and protocol that enables browser applications to communicate with gRPC services through an Envoy or Nginx proxy.

## Install

Save as a script file and run:

# gRPC-Web — gRPC for Browser Clients

## Quick Use
```bash
npm install grpc-web google-protobuf
# Generate client stubs
protoc -I=. service.proto 
  --js_out=import_style=commonjs:. 
  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:.
```

## 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/

---
Source: https://tokrepo.com/en/workflows/asset-547c0270
Author: Script Depot