gRPC Clients for Node.js and Web: Architecture and Implementation Compared

Choosing the right gRPC library depends entirely on where your code runs. @grpc/grpc-js is built for Node.js servers, while grpc-web and @improbable-eng/grpc-web are designed for browsers. Mixing them up leads to build failures or runtime errors. Let's break down how they handle environment support, setup, and API design.

🖥️ Runtime Environment: Server vs. Browser

@grpc/grpc-js runs exclusively on Node.js.

• It relies on Node's native http2 module.
• Bundling this for the browser will fail because browser environments lack Node core modules.

// @grpc/grpc-js: Server-side only
const { Client, credentials } = require('@grpc/grpc-js');
const client = new Client('localhost:50051', credentials.createInsecure());
// ❌ Will throw error if bundled for webpack/vite in browser

grpc-web runs in browsers.

• It uses HTTP/1.1 or HTTP/2 over standard web requests.
• Requires a proxy (like Envoy) to translate between browser and gRPC server.

// grpc-web: Browser client (generated code)
const { GreeterClient } = require('./proto/helloworld_grpc_web_pb');
const client = new GreeterClient('https://api.example.com', null, null);
// ✅ Works in browser via XHR or Fetch

@improbable-eng/grpc-web runs in browsers.

• It implements the gRPC-Web protocol using standard Fetch or XHR.
• Also requires a gRPC-Web compatible proxy on the server side.

// @improbable-eng/grpc-web: Browser client
import { createClientFactory } from '@improbable-eng/grpc-web';
const client = createClientFactory().create(MyService);
// ✅ Works in browser, handles transport internally

🛠️ Setup and Code Generation

@grpc/grpc-js uses standard protoc plugins.

• You generate JS code using grpc_tools_node_protoc_plugin.
• The generated code matches the Node.js runtime expectations.

// @grpc/grpc-js: Generation command
protoc --js_out=import_style=commonjs,binary:. \
  --grpc_out=grpc_js:. \
  --plugin=protoc-gen-grpc=./node_modules/.bin/grpc_tools_node_protoc_plugin \
  service.proto

grpc-web requires specific web plugins.

• You must use protoc-gen-grpc-web to generate compatible code.
• The output often relies on Closure Library or specific CommonJS wrappers.

// grpc-web: Generation command
protoc --js_out=import_style=commonjs:. \
  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. \
  service.proto

@improbable-eng/grpc-web uses its own plugin or compatible output.

• It can often consume standard gRPC-Web generated files but wraps them for TS.
• Historically offered better TypeScript type inference without extra steps.

// @improbable-eng/grpc-web: Generation command
protoc --js_out=import_style=commonjs:. \
  --grpc-web_out=import_style=commonjs,mode=grpcwebtext:. \
  service.proto
// Then wrap with @improbable-eng/grpc-web utilities

🔌 API Style: Callbacks vs. Promises

@grpc/grpc-js leans heavily on callbacks.

• Methods accept a callback function for responses.
• Streaming uses event emitters.

// @grpc/grpc-js: Callback style
client.sayHello(request, (err, response) => {
  if (err) console.error(err);
  else console.log(response.message);
});

grpc-web uses callbacks in generated code.

• The official generated clients expect (err, response) signatures.
• Promises require manual wrapping or helper libraries.

// grpc-web: Callback style
client.sayHello(request, { customHeader: 'value' }, (err, response) => {
  if (err) console.error(err);
  else console.log(response.getMessage());
});

@improbable-eng/grpc-web supports Promises natively.

• Offers a cleaner async/await experience.
• Reduces boilerplate for frontend developers used to Fetch API.

// @improbable-eng/grpc-web: Promise style
const response = await client.sayHello(request, {
  headers: new Headers({ customHeader: 'value' })
});
console.log(response.message);

🌐 Proxy and Infrastructure Requirements

@grpc/grpc-js connects directly to gRPC servers.

• No proxy needed if both sides are Node.js.
• Direct HTTP/2 connection over TCP.

// @grpc/grpc-js: Direct connection
// Client -> Node.js Server (Port 50051)

grpc-web requires an Envoy proxy.

• Browsers cannot speak raw gRPC over HTTP/2.
• Envoy translates gRPC-Web frames to standard gRPC.

// grpc-web: Proxy required
// Browser -> Envoy (HTTP/1.1 or HTTP/2) -> Node.js Server

@improbable-eng/grpc-web also requires a proxy.

• Compatible with the same Envoy setup as official grpc-web.
• Some configurations allow direct connection if server supports CORS and gRPC-Web frames.

// @improbable-eng/grpc-web: Proxy required
// Browser -> Envoy -> Node.js Server

📦 Maintenance and Ecosystem Health

@grpc/grpc-js is actively maintained by Google.

• It is the default for Node.js gRPC.
• Receives regular security updates and feature additions.

// @grpc/grpc-js: Stable API
// Safe for long-term enterprise use

grpc-web is actively maintained by Google.

• It is the standard for web gRPC.
• Documentation and tooling are official.

// grpc-web: Stable API
// Safe for long-term enterprise use

@improbable-eng/grpc-web is in maintenance mode.

• The repository indicates reduced activity.
• New projects should weigh the risk of reduced support against DX benefits.

// @improbable-eng/grpc-web: Maintenance Mode
// ⚠️ Check repository status before committing

📊 Summary: Key Differences

💡 The Big Picture

@grpc/grpc-js is the engine for your backend.
Use it to connect microservices within your server infrastructure. It is not an option for frontend code.

grpc-web is the standard bridge for browsers.
Use it if you want official support and long-term stability. It requires setting up a proxy, but it ensures you are following the canonical gRPC-Web spec.

@improbable-eng/grpc-web is the developer-friendly alternative.
Use it if you prioritize TypeScript experience and Promise-based APIs. However, because it is in maintenance mode, you must decide if the improved DX is worth the potential risk of slower updates in the future.

Final Thought: For new projects, pairing @grpc/grpc-js on the server with official grpc-web on the client is the safest architectural choice. If you choose @improbable-eng/grpc-web, plan for a potential migration path should support cease entirely.