gRPC-Web

You are a backend engineer setting up gRPC-Web infrastructure. The user wants to enable browser clients to communicate with gRPC services using gRPC-Web protocol.

What to check first

• Verify protoc compiler is installed: protoc --version
• Install protoc-gen-grpc-web plugin: npm install -g protoc-gen-grpc-web
• Confirm your gRPC server is running on a specific port (e.g., :50051)

Steps

1. Define your .proto service file with RPC methods using standard service declaration syntax
2. Generate JavaScript/TypeScript client stubs using protoc with the grpc-web plugin and --js_out=import_style=commonjs flag
3. Install @grpc/grpc-js and @improbable-eng/grpc-web in your client project
4. Create an HTTP/2 envoy proxy configuration to translate HTTP/1.1 gRPC-Web requests from browsers to HTTP/2 gRPC for your backend
5. Deploy the Envoy proxy on a publicly accessible endpoint (typically same origin or CORS-enabled)
6. Initialize gRPC-Web client with the proxy URL endpoint instead of direct gRPC server address
7. Make unary and streaming RPC calls through the generated client stub methods
8. Handle gRPC metadata and status codes in .then() and .catch() promise chains

Code

// 1. Client initialization (browser/Node.js client)
const { GreeterClient } = require('./generated/helloworld_grpc_web_pb');
const { HelloRequest } = require('./generated/helloworld_pb');

const client = new GreeterClient('http://localhost:8080', null, null);

// 2. Make unary RPC call
const request = new HelloRequest();
request.setName('World');

const metadata = { 'custom-header': 'value' };

client.sayHello(request, metadata, (err, response) => {
  if (err) {
    console.error('Error:', err.code, err.message);
    return;
  }
  console.log('Response:', response.getMessage());
});

// 3. Alternative: Promise-based call
client.sayHello(request, metadata)
  .then(response => {
    console.log('Got message:', response.getMessage());
  })
  .catch(err => {
    console.error('RPC failed:', err);
  });

// 4. Server-streaming call
const stream = client.listGreetings(request, metadata);

stream.on('data', response => {
  console.log('Stream data:', response.getMessage());
});

stream.on('end', () => {
  console.log('Stream ended');
});

stream.on('status', status => {
  console.log('Status code:', status.code);
});

stream.on('error', err =>

Note: this example was truncated in the source. See the GitHub repo for the latest full version.

Common Pitfalls

• Treating this skill as a one-shot solution — most workflows need iteration and verification
• Skipping the verification steps — you don't know it worked until you measure
• Applying this skill without understanding the underlying problem — read the related docs first

When NOT to Use This Skill

• When a simpler manual approach would take less than 10 minutes
• On critical production systems without testing in staging first
• When you don't have permission or authorization to make these changes

How to Verify It Worked

• Run the verification steps documented above
• Compare the output against your expected baseline
• Check logs for any warnings or errors — silent failures are the worst kind

Production Considerations

• Test in staging before deploying to production
• Have a rollback plan — every change should be reversible
• Monitor the affected systems for at least 24 hours after the change