grpcity

library3.0.0jsnpmunverified

gRPCity is a batteries-included gRPC framework for Node.js that wraps @grpc/grpc-js and @grpc/proto-loader behind an opinionated, promise-first API. Version 3.0.0, released 2023, requires Node >=18 and is actively maintained. Key differentiators vs raw @grpc/grpc-js: one loader reused across client/server, Koa-style middleware on both sides, sensible defaults for channel options and retry, built-in reflection, AbortSignal support, and runtime validation with zod. Written in TypeScript with complete type exports.

devops

npm install grpcity

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · GRPCITY

grpcity

devopsjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

ProtoLoader

✓ import { ProtoLoader } from 'grpcity'

✗ const { ProtoLoader } = require('grpcity')

ESM-only since v3. CommonJS require will not work.

gRPCServer

✓ import { gRPCServer } from 'grpcity'

✗ import gRPCServer from 'grpcity'

Named export, not default.

gRPCClient

✓ import { gRPCClient } from 'grpcity'

Named export. Type imports available: import type { gRPCClientOptions } from 'grpcity'

Shows full setup: proto loading, server with one service, client creation, and a unary RPC call.

import { ProtoLoader, gRPCServer, gRPCClient } from 'grpcity'; import path from 'node:path'; import { fileURLToPath } from 'node:url'; import { createServer } from 'node:http'; const __dirname = path.dirname(fileURLToPath(import.meta.url)); // 1. Load proto const loader = new ProtoLoader({ location: path.join(__dirname, './'), files: ['greeter.proto'] }); // 2. Define service class class Greeter { async sayGreet(ctx) { const { message } = ctx.request; return { message: `hello ${message || 'world'}` }; } } // 3. Start server const server = new gRPCServer(loader, { services: [{ serviceName: 'helloworld.Greeter', implementation: Greeter }] }); server.bind('0.0.0.0:50051', { useInsecure: true }); // 4. Create client const client = new gRPCClient(loader, { address: 'localhost:50051', useInsecure: true }); // 5. Make a call async function main() { const response = await client.call('helloworld.Greeter', 'SayGreet', { message: 'gRPCity' }); console.log('Response:', response.message); } main().catch(console.error);

Debug

Known issues

breakinggRPCity v3 dropped CommonJS support. Only ESM imports work.

fix

Switch project to ESM (type: module in package.json) and use import syntax.

affects: >=3.0.0

gotcha__dirname is not available in ESM; must derive from import.meta.url or use import.meta.dirname (Node >=20.11).

fix

Use import.meta.dirname or fileURLToPath(import.meta.url) for directory path.

affects: >=3.0.0

deprecatedThe useInsecure option is for development only. Production requires TLS.

fix

Configure credentials with { credentials: grpc.credentials.createSsl() } for production.

affects: >=1.0.0

gotchaClient call expects method name in PascalCase exactly as defined in proto.

fix

Ensure method name matches proto rpc name (e.g., 'SayGreet' not 'sayGreet').

affects: >=3.0.0

Errors

Common errors & fixes

Error: Cannot find module 'grpcity'

Package not installed or wrong import path.

fix

npm install grpcity

TypeError: grpcity.ProtoLoader is not a constructor

Using CommonJS require instead of ESM import.

fix

Change project to ESM (type: module) and use import { ProtoLoader } from 'grpcity'

Error: ENOENT: no such file or directory, open '.../greeter.proto'

Proto file location or filename mismatch.

fix

Verify location and files in ProtoLoader options; use path.resolve for absolute paths.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

@grpc/grpc-jsrequiredCore gRPC implementation

@grpc/proto-loaderrequiredDynamic proto file loading

zodrequiredRuntime option validation

Agent activity

6 hits · last 30 days

node

Resources

githubhttps://github.com/chakhsu/grpcity ↗

packagegrpcity ↗

homepagehttps://github.com/chakhsu/grpcity ↗