How grpc/grpc-web works
Project type and purpose
• This is an open-source library and code-generation tool (“grpc-web”) that lets browser clients use gRPC services.
• It contains two core deliverables:
• A runtime JavaScript/TypeScript client library (in javascript/net/grpc/web and packages/grpc-web)
• A protoc plugin (in javascript/net/grpc/web/generator) to generate JS/TS gRPC stubs from .proto files
• It also bundles examples (net/grpc/gateway/examples), tests, a Docker-Compose demo, and build scripts (Makefile, Bazel, scripts/).
File structure
• Top-level directories:
• javascript/net/grpc/web → runtime client code (JS/TS interfaces, transport, interceptors)
• javascript/net/grpc/web/generator → code generator source (C++/Zig + Bazel)
• packages/grpc-web → npm packaging, test harness, build scripts
• net/grpc/gateway/examples → demo services (Node.js server), Envoy configs, client web apps
• scripts/, docker-compose.yml → CI, build/test orchestration
• src/proto, test/interop → shared proto definitions and interop tests
• Build tools: Bazel (MODULE.bazel), Docker (docker-compose.yml, .dockerignore), npm/Gulp (packages/grpc-web).
README for insights
• Describes a typical workflow:
1. Service in .proto
2. Run protoc + protoc-gen-js + protoc-gen-grpc-web → generates *_pb.js + *_grpc_web_pb.js (+ .d.ts)
3. Bundle with Webpack/Browserify/Closure → browser app
4. Browser calls gRPC-Web → Envoy proxy → real gRPC server
• Highlights architecture: client library, proxy (Envoy or alternative), server frameworks.
• From developer tools → generated stubs → bundler → browser
• From browser → proxy → backend → proxy → browser
• Tools/Build (gray gears)
• Codegen plugins (blue hexagons)
Detail
• Every stage: .proto definitions, plugins, bundler, client runtime, network hops, server
• Don’t omit the test/CI flows or packaging steps for npm/Bazel
• That the generator is itself built by Bazel and packaged alongside the runtime