gRPC-Web: Calling gRPC from the Browser
On this page
Why browsers can't call gRPC directly
gRPC depends on HTTP/2 features that browser JavaScript can't control: it needs trailers (the status arrives after the body, Day 7) and fine-grained control of HTTP/2 framing. The fetch API doesn't expose trailers. So a web app can't call a gRPC server directly, even over HTTP/2.
Option 1: gRPC-Web with a proxy
gRPC-Web is a variant protocol that browsers can speak: the status and trailers move into the response body, and it works over HTTP/1.1 or HTTP/2. A proxy translates between gRPC-Web and normal gRPC:
Browser (gRPC-Web client) --HTTP/1.1 or 2, gRPC-Web framing--> Envoy (grpc_web filter) --gRPC--> OrderServiceEnvoy's envoy.filters.http.grpc_web filter does the translation, and some servers (grpc-dotnet, Connect-based servers) accept gRPC-Web directly without a proxy.
Limitations:
- Unary and server streaming only. Client streaming and bidirectional streaming aren't supported from browsers.
- An extra proxy hop and CORS configuration.
Option 2: the Connect protocol
Connect (from Buf) is a protocol, and a set of libraries, that serves the same .proto service over three protocols at once: gRPC, gRPC-Web and its own simple HTTP protocol. Connect requests are plain HTTP POSTs with JSON or binary bodies, so they're easy to call from fetch and debug with curl:
curl -H 'Content-Type: application/json' \
-d '{"order_id":"ord_42"}' https://api.example.com/shop.v1.OrderService/GetOrderConnect-ES generates TypeScript clients for browsers; Connect-Go servers need no translating proxy. The same streaming limits apply in browsers.
Option 3: a JSON gateway with gRPC-Gateway or Envoy
gRPC-Gateway (Go) or Envoy's gRPC-JSON transcoder expose gRPC methods as REST endpoints, using HTTP annotations in the .proto:
import "google/api/annotations.proto";
service OrderService {
rpc GetOrder(GetOrderRequest) returns (GetOrderResponse) {
option (google.api.http) = { get: "/v1/orders/{order_id}" };
}
}Now GET /v1/orders/ord_42 returns JSON, generated from the same contract. Good for public REST APIs and clients that know nothing about gRPC; you also get an OpenAPI description generated from the annotations.
gRPC-Web vs Connect vs JSON gateway
| Need | Option |
|---|---|
| Your own web app, typed client, streaming updates | Connect or gRPC-Web |
| Already running Envoy | gRPC-Web filter |
| Public or partner REST API from the same services | gRPC-Gateway or transcoding |
| Bidirectional streaming in the browser | WebSockets or server-sent events alongside, since gRPC-Web can't |
Protobuf JSON mapping details
Browser clients usually see JSON at some point, so remember the JSON mapping rules (Day 21): field names become lowerCamelCase, 64-bit integers become strings, enums become their names, and default values are omitted unless you ask for them.
Check yourself
Browser fetch APIs can't read HTTP trailers or control HTTP/2 framing, and gRPC relies on trailers for status and on framing for streaming. gRPC-Web and Connect move the status into the body so browsers can work with it.
Unary and server streaming. Client and bidirectional streaming don't work, because browser fetch APIs can't stream request bodies in a way gRPC-Web supports. Use WebSockets or separate calls for those patterns.
Add google.api.http annotations to RPCs, mapping each to an HTTP method and path, and use gRPC-Gateway or Envoy's transcoding filter to turn REST and JSON requests into gRPC calls.
A protocol from Buf that works over HTTP/1.1 and HTTP/2 with plain JSON or protobuf, so browsers can call services directly, while servers still speak gRPC too.