@grpc/grpc-js

@grpc/grpc-js is the official pure-JavaScript implementation of gRPC for Node.js, replacing the earlier C++-addon-based grpc package. It implements the core gRPC functionality — clients, servers, streaming calls, metadata, interceptors, load balancing policies, connection keepalives, and HTTP proxy support — entirely in TypeScript/JavaScript, so it runs on any platform supported by Node.js without native compilation.

The package is one part of the grpc-node monorepo, which also includes @grpc/proto-loader for compiling .proto files into runtime objects, grpc-tools for the protoc compiler and code generator, and smaller supporting services like @grpc/reflection and grpc-health-check. @grpc/grpc-js is the library most applications install directly to build gRPC clients and servers.

What You Get

• Client and Server classes implementing the full gRPC call lifecycle: unary, client-streaming, server-streaming, and bidirectional streaming
• Client interceptors and call/channel credentials for auth, TLS, and custom metadata handling
• Pick-first and round-robin load balancing policies with automatic reconnection and connection keepalives
• HTTP CONNECT proxy support for calling gRPC services through corporate proxies
• Channelz-based introspection and configurable channel options for tuning message size, retries, and connection lifetime
• A migration path and documented API differences for teams moving off the deprecated native grpc package

Common Use Cases

• Building internal microservice-to-microservice RPC communication in Node.js backends
• Implementing gRPC servers that Kubernetes-based or polyglot service meshes call into
• Consuming gRPC APIs exposed by other languages (Go, Java, Python) from a Node.js client
• Streaming large datasets or real-time updates between services using server- or bidirectional-streaming RPCs
• Adding health-check and reflection endpoints to Node.js gRPC servers using the companion grpc-health-check and @grpc/reflection packages

Under The Hood

Architecture - The library centers on Channel (packages/grpc-js/src/channel.ts), which manages subchannels, connectivity state transitions, and name resolution, while Client and Server build the request/response call lifecycle on top of it via call.ts and call-interface.ts. Load balancing is pluggable through pick-first and round-robin policies, and filter-stack.ts/filter.ts implement a middleware-style pipeline (compression, deadlines, auth) that every call passes through, letting cross-cutting concerns like compression and interceptors compose independently of the core transport logic.

Tech Stack - Written entirely in TypeScript, compiled to CommonJS with generated protobuf types under src/generated, and built with a Gulp-based toolchain shared across the grpc-node monorepo’s packages. It has no native/C++ dependency, distinguishing it from the deprecated grpc package, and its main runtime dependency is @grpc/proto-loader for decoding .proto-defined message types.

Code Quality - The grpc-js package’s test/ directory contains 33+ top-level test files covering channel state transitions, load balancing, interceptors, credentials, and streaming behavior, run via Mocha as part of the monorepo’s shared CI. The README documents an explicit semantic-versioning policy, including which APIs (underscore-prefixed methods, the Call class, the experimental namespace) are excluded from that guarantee — a level of API-stability discipline uncommon in comparable libraries.

API Design - The API is intentionally close to the deprecated native grpc package to ease migration, with a documented list of behavioral differences (e.g. Server#bindAsync replacing Server#bind) and a full channel-argument compatibility table in PACKAGE-COMPARISON.md. Getting started requires loading a .proto file through @grpc/proto-loader and passing the resulting package definition into grpc.loadPackageDefinition(), which is a small amount of boilerplate but keeps the core library decoupled from any specific protobuf-loading strategy.