koa-grpc

library1.0.6jsnpmunverified

A gRPC middleware for Koa that allows building gRPC servers using the familiar Koa middleware pattern. It wraps gRPC services into Koa-style context, enabling middleware chains, routing via koa-mount, and request/response handling with `ctx.request`, `ctx.body`, and `ctx.call`. Current stable version 1.0.6, no recent releases. Differentiators: integrates gRPC with Koa's composable middleware, supports async/await, and uses protobuf generated code via @grpc/proto-loader or grpc-tools.

messaging

npm install koa-grpc

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · KOA-GRPC

koa-grpc

messagingjavascriptv1.0.6

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.

KoaGrpc

✓ import KoaGrpc from 'koa-grpc'

✗ const KoaGrpc = require('koa-grpc')

ESM default export; CommonJS require works but break TypeScript type inference. Use default import for types.

Context

✓ import { Context } from 'koa'

✗ import { Context } from 'koa-grpc'

Context is re-exported from koa-grpc types, but Koa's own Context is preferred.

KoaGrpc type

✓ import type { KoaGrpc } from 'koa-grpc'

✗ import { KoaGrpc } from 'koa-grpc'

For type-only imports, use `import type` to avoid value import error.

Shows basic setup with a gRPC service and a route handler that responds to 'sayHello' method.

import { Context } from 'koa'; import KoaGrpc from 'koa-grpc'; const mount = require('koa-mount'); var { GreeterService } = require('./gen_code/helloworld_grpc_pb'); var messages = require('./gen_code/helloworld_pb'); const app = new KoaGrpc({ service: GreeterService }); app.use( mount('/sayHello', function (ctx: Context) { console.log('ctx.request: ', (ctx.request as any).getName()); var reply = new messages.HelloReply(); reply.setMessage('Hello ' + ctx.call.request.getName()); ctx.body = reply; }) ); app.listen('0.0.0.0:50051'); console.log('listening on 50051...');

Debug

Known issues

breakingKoaGrpc constructor requires { service } option; no service will cause runtime error

fix

Pass an object with service property: new KoaGrpc({ service: MyService })

affects: >=1.0.0

gotchactx.request is a gRPC request object, not a Koa request; cast to any to access methods like getName()

fix

Use (ctx.request as any).getName() or extend types

affects: >=1.0.0

deprecatedmount is from koa-mount package, not built-in; avoid using deprecated koa-mount v1

fix

Install koa-mount and require it, or use @koa/mount

affects: >=1.0.0

gotchactx.call is the gRPC call object; ctx.call.request is the proto request, not ctx.request

fix

Use ctx.call.request to access request fields

affects: >=1.0.0

gotchaProto files must be compiled manually with grpc-tools; no automatic code generation

fix

Run grpc_tools_node_protoc as shown in README

affects: >=1.0.0

Errors

Common errors & fixes

Error: 12 UNIMPLEMENTED: Not Found

No route handler matched the gRPC method

fix

Add a route with mount for the method path, e.g., app.use(mount('/sayHello', handler))

TypeError: Cannot read property 'getName' of undefined

ctx.call.request is undefined because the request hasn't been parsed or the method is unknown

fix

Ensure the gRPC service definition includes the method and request type is correctly imported

TypeError: ctx.request.getName is not a function

ctx.request is not the gRPC request object; it's a Koa request

fix

Cast ctx.request to any: (ctx.request as any).getName()

Upgrade

Version history

1.0.6latest on npm

Audit

Dependencies

koarequiredExtends Koa's Application class and uses Koa Context and middleware pattern.

grpcrequiredUnderlying gRPC implementation for Node.js.

Agent activity

13 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/cooperhsiung/koa-grpc ↗

packagekoa-grpc ↗

homepagehttps://github.com/cooperhsiung/koa-grpc#readme ↗