Required dependencies

npm install @js-sdsl/ordered-map
npm install @grpc/proto-loader

No native build steps, no pod install, no NDK configuration required. Runs on any Node.js ≥ 12 platform.

Project setup

1. Copy source/ into your project, e.g. at src/grpc-js/.
2. Update tsconfig.json to include the new source tree and enable needed options:

{
  "compilerOptions": {
    "target": "ES2019",
    "module": "commonjs",
    "moduleResolution": "node",
    "esModuleInterop": true,
    "resolveJsonModule": true,
    "strict": true,
    "paths": {
      "@grpc/grpc-js": ["./src/grpc-js/index"]
    }
  },
  "include": ["src"]
}

3. In your application code, import from the local path alias instead of the npm package:

import * as grpc from '@grpc/grpc-js';

4. Optional environment variables:

Public API

Server

class Server {
  constructor(options?: ServerOptions);
  addService(service: ServiceDefinition, implementation: UntypedServiceImplementation): void;
  bindAsync(port: string, creds: ServerCredentials, cb: (err: Error | null, port: number) => void): void;
  start(): void;
  forceShutdown(): void;
  tryShutdown(cb: (err?: Error) => void): void;
}

Use Server to host gRPC services. Call addService with a generated service definition and your handler object, then bindAsync with a ServerCredentials instance, then start().

makeClientConstructor

function makeClientConstructor(
  methods: ServiceDefinition,
  serviceName: string,
  classOptions?: {}
): typeof Client;

Generates a typed client class from a ServiceDefinition (usually produced by @grpc/proto-loader). The returned constructor accepts (address, credentials, options?). Use this when you have a proto-loaded service object but are not using the loadPackageDefinition convenience wrapper.

Metadata

class Metadata {
  constructor(options?: MetadataOptions);
  add(key: string, value: MetadataValue): void;
  set(key: string, value: MetadataValue): void;
  get(key: string): MetadataValue[];
  remove(key: string): void;
  clone(): Metadata;
  merge(other: Metadata): void;
  toJSON(): { [key: string]: MetadataValue[] };
}

Metadata carries gRPC headers for both clients (outgoing call metadata) and servers (initial/trailing metadata). Pass a Metadata instance to any call method or send it from a server handler via call.sendMetadata(meta).

ChannelCredentials

class ChannelCredentials {
  static createInsecure(): ChannelCredentials;
  static createSsl(
    rootCerts?: Buffer | null,
    privateKey?: Buffer | null,
    certChain?: Buffer | null,
    verifyOptions?: VerifyOptions
  ): ChannelCredentials;
}

Required when creating a client channel. Use createInsecure() for local/dev connections; use createSsl() for production with mutual TLS.

StatusBuilder

class StatusBuilder {
  withCode(statusCode: Status): this;
  withDetails(details: string): this;
  withMetadata(metadata: Metadata): this;
  build(): Partial<StatusObject>;
}

Fluent builder for composing StatusObject values in server handlers or test assertions.

Working examples

Scenario - Unary RPC client

A Node.js client calling a remote Greeter.SayHello unary method using a proto-loader-generated definition.

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import path from 'path';

const packageDef = protoLoader.loadSync(
  path.join(__dirname, 'protos/helloworld.proto'),
  { keepCase: true, longs: String, enums: String, defaults: true, oneofs: true }
);
const proto = grpc.loadPackageDefinition(packageDef) as any;

const client = new proto.helloworld.Greeter(
  'localhost:50051',
  grpc.ChannelCredentials.createInsecure()
);

const meta = new grpc.Metadata();
meta.add('x-request-id', 'abc-123');

client.sayHello({ name: 'World' }, meta, (err: grpc.ServiceError | null, response: any) => {
  if (err) {
    console.error('RPC error:', err.code, err.message);
    return;
  }
  console.log('Response:', response.message);
});

Scenario - Unary RPC server

Hosting a Greeter service with a simple unary handler.

import * as grpc from '@grpc/grpc-js';
import * as protoLoader from '@grpc/proto-loader';
import path from 'path';

const packageDef = protoLoader.loadSync(
  path.join(__dirname, 'protos/helloworld.proto')
);
const proto = grpc.loadPackageDefinition(packageDef) as any;

function sayHello(
  call: grpc.ServerUnaryCall<{ name: string }, { message: string }>,
  callback: grpc.sendUnaryData<{ message: string }>
) {
  callback(null, { message: `Hello ${call.request.name}` });
}

const server = new grpc.Server();
server.addService(proto.helloworld.Greeter.service, { sayHello });

server.bindAsync(
  '0.0.0.0:50051',
  grpc.ServerCredentials.createInsecure(),
  (err, port) => {
    if (err) throw err;
    console.log(`Listening on ${port}`);
    server.start();
  }
);

Scenario - Mutual TLS client and server

Production setup with TLS certificates on both sides.

import * as grpc from '@grpc/grpc-js';
import * as fs from 'fs';

// Server
const serverCreds = grpc.ServerCredentials.createSsl(
  fs.readFileSync('certs/ca.crt'),
  [{ private_key: fs.readFileSync('certs/server.key'), cert_chain: fs.readFileSync('certs/server.crt') }],
  true // checkClientCertificate
);

const server = new grpc.Server();
// ... addService ...
server.bindAsync('0.0.0.0:50051', serverCreds, (err, port) => {
  if (err) throw err;
  server.start();
});

// Client
const clientCreds = grpc.ChannelCredentials.createSsl(
  fs.readFileSync('certs/ca.crt'),
  fs.readFileSync('certs/client.key'),
  fs.readFileSync('certs/client.crt')
);
// const client = new MyServiceClient('hostname:50051', clientCreds);

Scenario - Attaching call credentials (token-based auth)

import * as grpc from '@grpc/grpc-js';

const callCreds = grpc.CallCredentials.createFromMetadataGenerator(
  (params, callback) => {
    const meta = new grpc.Metadata();
    meta.add('authorization', `Bearer my-token`);
    callback(null, meta);
  }
);

const channelCreds = grpc.ChannelCredentials.createSsl();
const combinedCreds = channelCreds.compose(callCreds);
// const client = new MyServiceClient('api.example.com:443', combinedCreds);

File walkthrough

• index.ts — Aggregates and re-exports the entire public surface of the library.
• server.ts — Core Server class: HTTP/2 binding, service registry, graceful shutdown.
• client.ts — Client base class with call dispatch, options, and interceptor support.
• make-client.ts — Factory utilities that turn a ServiceDefinition into a Client subclass.
• channel.ts — Channel interface and ChannelImplementation: connection lifecycle and state.
• internal-channel.ts — Internal channel plumbing used by Client and load balancers.
• call-credentials.ts — CallCredentials factory (metadata generators, OAuth2, composition).
• channel-credentials.ts — ChannelCredentials for insecure and TLS channel security.
• metadata.ts — Metadata container for gRPC headers; handles binary (-bin) keys automatically.
• server-call.ts — Typed server-side call objects and handler type aliases.
• server-credentials.ts — ServerCredentials for insecure and TLS listener security.
• server-interceptors.ts — Server interceptor interfaces and listener chain types.
• call.ts — Client-side stream types returned by stub methods.
• call-interface.ts — Shared interfaces: StatusObject, WriteObject, InterceptingListener.
• resolver.ts — Resolver plugin registration API and ResolverListener.
• resolver-dns.ts — DNS SRV/A/AAAA resolver implementation.
• resolver-ip.ts — Literal IP address resolver.
• resolver-uds.ts — Unix domain socket resolver.
• load-balancer.ts — Load-balancer plugin registration and LoadBalancer interface.
• load-balancer-round-robin.ts — Round-robin policy implementation.
• load-balancer-pick-first.ts — Pick-first policy implementation.
• load-balancer-weighted-round-robin.ts — Weight-aware round-robin policy.
• load-balancer-outlier-detection.ts — Outlier detection wrapping policy.
• load-balancer-child-handler.ts — Utility for LB policies that wrap another policy.
• retrying-call.ts — Hedging and retry call wrapper with RetryThrottler.
• resolving-call.ts — Call layer that waits for name resolution before proceeding.
• resolving-load-balancer.ts — Combines resolver and LB into a single entity.
• load-balancing-call.ts — Call layer sitting between retries and the subchannel picker.
• service-config.ts — Parses and validates gRPC service config (retry, LB, method config).
• channelz.ts — Full channelz gRPC service implementation for runtime introspection.
• admin.ts — registerAdminService to add channelz/CSDS to an existing server.
• subchannel.ts — Subchannel lifecycle: connect, disconnect, HTTP/2 session.
• subchannel-pool.ts — Shared pool that de-duplicates subchannels by address.
• subchannel-address.ts — SubchannelAddress type plus TCP/UDS helpers.
• subchannel-call.ts — Single HTTP/2 stream call executing on a subchannel.
• subchannel-interface.ts — SubchannelInterface type used across LB layers.
• transport.ts — HTTP/2 transport abstraction, CallEventTracker.
• tls-helpers.ts — Reads default root CA certs, builds SecureContext.
• uri-parser.ts — Parses gRPC target strings into GrpcUri.
• status-builder.ts — Fluent StatusBuilder for constructing status objects.
• stream-decoder.ts — Decodes gRPC length-prefixed message frames.
• filter.ts / filter-stack.ts — Composable client-side interceptor filter chain.
• client-interceptors.ts — Client interceptor call wrapper and types.
• logging.ts — trace() and log() with verbosity gating.
• constants.ts — Status (gRPC status codes), LogVerbosity, Propagate enums.
• connectivity-state.ts — ConnectivityState enum (IDLE, CONNECTING, READY, …).
• compression-filter.ts / compression-algorithms.ts — gzip/deflate/identity compression.
• deadline.ts — Deadline type (Date | number) and formatDateDifference.
• backoff-timeout.ts — Exponential-backoff timer with jitter.
• http_proxy.ts — Detects and tunnels through HTTP CONNECT proxies.
• environment.ts — Reads GRPC_* environment variables.
• error.ts — getErrorMessage safe extraction from unknown errors.
• call-number.ts — Monotonically increasing call ID generator.
• object-stream.ts — Typed duplex/readable/writable stream helpers.
• events.ts — Internal event name constants.
• orca.ts — ORCA per-request load reporting via PerRequestMetricRecorder.
• auth-context.ts — AuthContext exposing per-connection TLS metadata.
• certificate-provider.ts — Plugin interface for dynamic certificate rotation.
• channel-options.ts — ChannelOptions keys and types (keepalive, max message sizes, etc.).
• duration.ts — Protobuf Duration conversions.
• control-plane-status.ts — xDS control plane NACK status helpers.
• priority-queue.ts — Min-heap priority queue used by LB subsystem.
• single-subchannel-channel.ts — A channel that always uses one specific subchannel.
• experimental.ts — Unstable APIs gated behind an explicit import.
• generated/ — Auto-generated TypeScript protobuf types for channelz, ORCA, and xDS protos.

Common pitfalls and fixes

• GRPC_VERBOSITY not set in production — the library defaults to no output; set GRPC_VERBOSITY=ERROR to surface real errors without trace noise.
• @js-sdsl/ordered-map missing — channelz.ts imports it directly; if your bundler tree-shakes it out, add it as an explicit dependency and verify it appears in node_modules.
• Proto-loader version mismatch — loadPackageDefinition expects objects produced by @grpc/proto-loader ≥ 0.6; older versions produce incompatible shapes.
• bindAsync called but start() forgotten — bindAsync only registers the port; the server does not accept connections until start() is explicitly called afterward.
• Binary metadata keys — keys ending in -bin must have Buffer values, not strings; passing a string throws at runtime inside Metadata.add.
• ESM projects — this source is CommonJS (module: commonjs); in an ESM project, use "type": "commonjs" in the source subtree's package.json or configure ts-node with esm: false.

Vibe-coding prompt template

I have the source of @grpc/grpc-js at src/grpc-js/ (entry point: src/grpc-js/index.ts)
and a USAGE.md file describing the full API.

Please integrate gRPC into my existing Node.js/TypeScript project by:
1. Reading USAGE.md and src/grpc-js/index.ts to understand the real exports.
2. Installing the required peer dependencies listed in USAGE.md § "Required dependencies".
3. Adding a path alias in tsconfig.json: "@grpc/grpc-js" -> ["./src/grpc-js/index"].
4. Creating src/grpc/server.ts that instantiates grpc.Server, registers my
   [SERVICE_NAME] service, binds on port [PORT] with insecure credentials, and starts.
5. Creating src/grpc/client.ts that builds a client stub for [SERVICE_NAME] using
   makeClientConstructor or loadPackageDefinition and ChannelCredentials.createInsecure().
6. Adding Metadata headers [HEADERS] to every outgoing call via CallCredentials.createFromMetadataGenerator.
7. Wiring the server into my existing Express app startup (src/app.ts) so both
   HTTP and gRPC start together.
Only use symbols present in src/grpc-js/index.ts or explicitly documented in USAGE.md.
Do not invent API surface. Show each file in full.

License and credit

Licensed under the Apache License 2.0 (see source/LICENSE if present, or the license header at the top of each source file). Upstream package: @grpc/grpc-js, part of the grpc-node monorepo maintained by the gRPC authors.

This product’s unique contribution is clean room implementation of valuable code block into AVCP compatible standard.

The full install guide and integration prompts unlock after purchase.

Got: Human-Friendly HTTP Request Library for Node.js

Automation, Utilities & Developer Tools

Free