{"id":47149,"library":"basic-grpc","title":"basic-grpc","description":"A minimal wrapper over grpc and @grpc/proto-loader for Node.js, aiming to simplify gRPC server and client setup. Version 0.0.3 is the current release with no regular release cadence noted. Unlike full-featured frameworks like gRPC-Web or NestJS gRPC, it provides a thin layer with TypeScript support, prototype service definitions, and helper functions for credentials, error handling, and server/client creation. Designed for developers who want a quick start with gRPC without managing the underlying grpc-js complexity directly.","status":"active","version":"0.0.3","language":"javascript","source_language":"en","source_url":null,"tags":["javascript"],"install":[{"cmd":"npm install basic-grpc","lang":"bash","label":"npm"},{"cmd":"yarn add basic-grpc","lang":"bash","label":"yarn"},{"cmd":"pnpm add basic-grpc","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core gRPC library used for server and client communication","package":"grpc","optional":false},{"reason":"Loads .proto files and generates service definitions","package":"@grpc/proto-loader","optional":false}],"imports":[{"note":"ESM-only; CommonJS require may not work depending on bundler. Use import statement.","wrong":"const { createServer } = require('basic-grpc')","symbol":"createServer","correct":"import { createServer } from 'basic-grpc'"},{"note":"ESM-only; CommonJS require may not work depending on bundler. Use import statement.","wrong":"const createClient = require('basic-grpc').createClient","symbol":"createClient","correct":"import { createClient } from 'basic-grpc'"},{"note":"ESM-only; CommonJS require may not work depending on bundler. Use import statement.","wrong":"const RPCError = require('basic-grpc').RPCError","symbol":"RPCError","correct":"import { RPCError } from 'basic-grpc'"},{"note":"ESM-only; CommonJS require may not work depending on bundler. Use import statement.","wrong":"const createServerCreds = require('basic-grpc').createServerCreds","symbol":"createServerCreds","correct":"import { createServerCreds } from 'basic-grpc'"},{"note":"ESM-only; CommonJS require may not work depending on bundler. Use import statement.","wrong":"const createClientCreds = require('basic-grpc').createClientCreds","symbol":"createClientCreds","correct":"import { createClientCreds } from 'basic-grpc'"},{"note":"TypeScript only; used for typing the server setup configuration.","wrong":"","symbol":"ISetup","correct":"import { ISetup } from 'basic-grpc'"},{"note":"TypeScript only; used for typing a service definition.","wrong":"","symbol":"IProtoService","correct":"import { IProtoService } from 'basic-grpc'"}],"quickstart":{"code":"import { createServer, createClient, RPCError, IProtoService, ISetup } from 'basic-grpc';\nimport { join } from 'path';\n\n// Server setup\nconst loginService: IProtoService<{ login: Function }> = {\n  protoFile: 'login.proto',\n  packageName: 'login',\n  serviceName: 'Login',\n  handlers: {\n    login: async ({ username, password }: { username: string; password: string }) => {\n      if (password === 'secret') return { token: 'abc123' };\n      throw new RPCError(22, 'Invalid credentials');\n    }\n  }\n};\n\nconst serverConfig: ISetup = {\n  protoRoot: join(__dirname, 'protos'),\n  services: [loginService]\n};\n\nconst server = createServer({\n  gRPCSetup: serverConfig,\n  domain: 'localhost:50051'\n});\nserver.start();\n\n// Client setup\nconst client = createClient<{ login: Function }>({\n  url: 'localhost',\n  port: '50051',\n  protoPath: join(__dirname, 'protos', 'login.proto'),\n  packageName: 'login',\n  serviceName: 'Login'\n});\n\nasync function main() {\n  const result = await client.login({ username: 'user', password: 'secret' });\n  console.log(result.token);\n}\nmain();","lang":"typescript","description":"Creates a gRPC server and client with a simple login service, demonstrating service definition, error handling, and client invocation."},"warnings":[{"fix":"Use import { ... } from 'basic-grpc' instead of 'simple-grpc'.","message":"Package name 'basic-grpc' but examples use 'simple-grpc'. Ensure correct import from 'basic-grpc'.","severity":"gotcha","affected_versions":"all"},{"fix":"For server: set protoRoot to directory containing .proto files. For client: set protoPath to full path including filename.","message":"Proto file path resolution: The protoRoot for server must be a directory, but protoPath for client must be the full path to the .proto file. Mixing them up causes load failure.","severity":"gotcha","affected_versions":"all"},{"fix":"Use known gRPC status codes (0-15) or custom codes > 15. See https://github.com/grpc/grpc/blob/master/doc/statuscodes.md","message":"RPCError code must be an integer >= 0. Custom codes start at 15+ per gRPC docs, but invalid codes may cause undefined behavior.","severity":"gotcha","affected_versions":"all"},{"fix":"Consider using '@grpc/grpc-js' directly or a wrapper that supports it.","message":"The 'grpc' package is being phased out in favor of '@grpc/grpc-js'. basic-grpc depends on 'grpc' which may require native compilation.","severity":"deprecated","affected_versions":">=0.0.3"}],"env_vars":null,"search_vec":"'0.0.3':22 'aim':13 'basic':2 'basic-grpc':1 'cadenc':31 'client':19 'complex':83 'creation':65 'credenti':60 'current':25 'definit':55 'design':66 'develop':68 'direct':84 'error':61 'featur':36 'framework':37 'full':35 'full-featur':34 'function':58 'grpc':3,8,16,40,44,75,81 'grpc-js':80 'grpc-web':39 'grpc/proto-loader':10 'handl':62 'helper':57 'javascript':85 'js':82 'layer':49 'like':38 'manag':77 'minim':5 'nestj':43 'node.js':12 'note':32 'prototyp':53 'provid':46 'quick':72 'regular':29 'releas':26,30 'server':17 'server/client':64 'servic':54 'setup':20 'simplifi':15 'start':73 'support':52 'thin':48 'typescript':51 'under':79 'unlik':33 'version':21 'want':70 'web':41 'without':76 'wrapper':6","created_at":"2026-06-07T16:50:03.140639+00:00","updated_at":"2026-06-07T16:50:03.140639+00:00","problems":[{"fix":"Run npm install grpc. If native compilation fails, ensure build tools are installed (e.g., build-essential on Linux, windows-build-tools on Windows).","cause":"Missing dependency: 'grpc' is required but not installed (or failing to compile).","error":"Error: Cannot find module 'grpc'"},{"fix":"Ensure the TypeScript interface used with createClient has a property matching the RPC method name (e.g., login). Check proto file and client declaration.","cause":"Client method not correctly typed or the service definition mismatches. The createClient generic may not match the actual RPC method name.","error":"TypeError: login is not a function"},{"fix":"Verify that protoFile, packageName, and serviceName in server match protoPath, packageName, and serviceName in client. Also ensure the .proto file is correctly loaded.","cause":"Service name, package name, or proto path mismatched between server and client definitions.","error":"Error: 20 UNIMPLEMENTED: Method not found: /login.Login/login"},{"fix":"Install '@grpc/proto-loader@0.5.x' (version 0.6.x changes API). Use npm install @grpc/proto-loader@0.5.0.","cause":"Incompatible version of '@grpc/proto-loader'. The package expects an older API.","error":"TypeError: grpc.loadPackageDefinition is not a function"}],"ecosystem":"npm","meta_description":null,"install_score":null,"quickstart_score":null,"quickstart_tag":null,"pypi_latest":null,"cli_name":null,"cli_version":null,"type":"library","homepage":null,"github":null,"docs":null,"changelog":null,"pypi":null,"npm":"basic-grpc","openapi_spec":null,"status_page":null,"smithery":null,"categories":["testing"],"base_url":null,"auth_type":null,"provenance":{"verified_status":null,"verified_at":null,"last_verified":"2026-06-07","next_check":"2026-09-05","install_tag":null}}