gRPCity

gRPCity is a batteries-included gRPC framework for Node.js. It wraps @grpc/grpc-js and @grpc/proto-loader behind a small, opinionated API so you can stand up a typed gRPC service or client in a handful of lines and stay focused on business logic.

What it does

gRPCity answers three questions that every Node.js gRPC project ends up asking:

• How do I load .proto files once and reuse them across the process?
• How do I write a client that’s promise-friendly, supports streaming, and reads cleanly?
• How do I write a server that’s just a class, with middleware where I expect it?

The framework collapses the boilerplate without hiding it. Loader, client, and server are three small surfaces that share state, so a single loader.init() is enough to drive everything else.

Why it exists

gRPCity grew out of running Node.js microservices in production. As traffic grows, the cost of every routing layer and every ad-hoc helper adds up. We wanted one library that did the boring parts — promisification, middleware, reflection, TLS, metadata — once and consistently, so service authors could spend their time on business code instead.

The first commit landed on October 28, 2019. Kamuel  wrote the original proto load and client proxy. Chakhsu  carried it forward with multi-proto load, the full client proxy, the server call proxy, and complete streaming support. The library now backs hundreds of services in production.

Design at a glance

The internal data flow is intentionally short:

.proto → this._packagePrefix → this._types:

init clients → get client → client proxy → rpc method call → do:

init server → instance → call proxy:

Features

• API — gRPC over HTTP/2, schemas defined in Protobuf.
• Protobuf — dynamic loading only; no codegen step.
• Client — configure once, call from anywhere; multi-server supported.
• Server — three-line bootstrap; multiple services per process.
• Credentials — full TLS support on both ends.
• No routing — RPC paths are bound to methods automatically.
• Middleware — Koa-style (ctx, next) on both client and server.
• Metadata — standard helpers for sending and reading metadata.
• Reflection — gRPC Server Reflection built in.
• Error — GrpcClientError carries code / details / metadata for precise catch handling.
• Promise & callback — async APIs by default, callback variants kept.
• AbortSignal — pass an AbortSignal to any RPC call to cancel it.
• Config — passthrough for any @grpc/proto-loader and @grpc/grpc-js channel option.
• Validation — loader, client and server options are validated at runtime with zod .
• TypeScript — written in TS with complete type exports.

…and a few more.

License

Released under the MIT License.