{"id":10976,"library":"grpc-node-server-reflection","title":"gRPC Node.js Server Reflection","description":"This package provides an implementation of gRPC Server Reflection for Node.js applications, specifically designed to work with the `@grpc/grpc-js` library. It enables gRPC clients, such as `grpccurl` or `Postman`, to dynamically discover the services, methods, and message types exposed by a gRPC server at runtime, without needing pre-compiled `.proto` files on the client side. The current stable version is 1.0.2. As a utility library, its release cadence is primarily driven by updates to its core dependency, `@grpc/grpc-js`, or bug fixes, rather than a fixed schedule. Its key differentiator is its straightforward integration method, requiring only a single function call to wrap an existing `@grpc/grpc-js` server instance, thereby abstracting the complex details of implementing the `grpc.reflection.v1alpha.ServerReflection` service manually. Currently, it fully supports `ListServices` and `FileContainingSymbol` requests but explicitly notes that `FileByFilename` and `FileContainingExtension` requests are not yet implemented.","status":"active","version":"1.0.2","language":"javascript","source_language":"en","source_url":"https://github.com/papajuanito/grpc-node-server-reflection","tags":["javascript","typescript"],"install":[{"cmd":"npm install grpc-node-server-reflection","lang":"bash","label":"npm"},{"cmd":"yarn add grpc-node-server-reflection","lang":"bash","label":"yarn"},{"cmd":"pnpm add grpc-node-server-reflection","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Required runtime dependency for gRPC server functionality.","package":"@grpc/grpc-js","optional":false}],"imports":[{"note":"The `wrapServerWithReflection` function is exported as a default export. Ensure you import it without curly braces. For CommonJS, `const wrapServerWithReflection = require('grpc-node-server-reflection');` is the correct pattern, not `require().wrapServerWithReflection`.","wrong":"import { wrapServerWithReflection } from 'grpc-node-server-reflection';","symbol":"wrapServerWithReflection","correct":"import wrapServerWithReflection from 'grpc-node-server-reflection';"}],"quickstart":{"code":"import * as grpc from '@grpc/grpc-js';\nimport wrapServerWithReflection from 'grpc-node-server-reflection';\n\n// A minimal example service for demonstration\nconst exampleServiceDefinition = {\n  ExampleService: {\n    sayHello: {\n      path: '/example.ExampleService/SayHello',\n      requestStream: false,\n      responseStream: false,\n      requestType: { deserializeBinary: () => ({ name: '' }) },\n      responseType: { serializeBinary: () => Buffer.from('') }\n    }\n  }\n};\n\nconst exampleServiceImplementation = {\n  sayHello: (call, callback) => {\n    callback(null, { message: `Hello, ${call.request.name || 'Guest'}!` });\n  }\n};\n\nfunction main() {\n  const server = new grpc.Server();\n\n  // IMPORTANT: Wrap the server with reflection *before* adding any services.\n  const reflectedServer = wrapServerWithReflection(server);\n\n  reflectedServer.addService(exampleServiceDefinition.ExampleService, exampleServiceImplementation);\n\n  reflectedServer.bindAsync(\n    '0.0.0.0:50051',\n    grpc.ServerCredentials.createInsecure(),\n    (err, port) => {\n      if (err) {\n        console.error(`Server bind failed: ${err}`);\n        return;\n      }\n      reflectedServer.start();\n      console.log(`Server running at http://0.0.0.0:${port}`);\n      console.log('Try: grpcurl -plaintext localhost:50051 list');\n      console.log('Or: grpcurl -plaintext localhost:50051 describe example.ExampleService');\n    }\n  );\n}\n\nmain();","lang":"typescript","description":"Demonstrates how to integrate server reflection into an existing `@grpc/grpc-js` server instance, ensuring services are discoverable via tools like `grpcurl`."},"warnings":[{"fix":"Always ensure you call `wrapServerWithReflection(yourServerInstance)` on your `grpc.Server` instance *before* adding any application-specific services using `yourServerInstance.addService(...)`.","message":"Application services added to the gRPC server *before* calling `wrapServerWithReflection` will not be correctly registered or discoverable via the reflection service. The wrapper intercepts `addService` calls.","severity":"breaking","affected_versions":">=1.0.0"},{"fix":"Clients should avoid sending `FileByFilename` or `FileContainingExtension` requests. Consult the package documentation for the supported reflection request types (`ListServices`, `FileContainingSymbol`).","message":"The library explicitly states that `FileByFilename` and `FileContainingExtension` reflection request types are not supported. Attempting to use these specific reflection queries will result in an error or unexpected behavior.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"fix":"Verify that `wrapServerWithReflection` has been successfully called on your `grpc.Server` instance. Also, confirm that your gRPC server is properly started and listening on the expected port.","cause":"The gRPC server reflection service itself has not been correctly added to the server, or the server is not running/accessible.","error":"grpcurl: rpc error: code = Unimplemented desc = Unknown method"},{"fix":"Reorder your server initialization. Call `wrapServerWithReflection(server)` first, then use the returned (wrapped) server object (`reflectedServer.addService(...)`) to register your application's services.","cause":"Your application's gRPC services were added to the server instance *before* `wrapServerWithReflection` was called. The reflection wrapper needs to intercept `addService` calls to track them.","error":"grpcurl: rpc error: code = Internal desc = Reflection service could not find symbol: [your_service_name]"}],"ecosystem":"npm"}