{"id":47726,"library":"gaia","title":"Gaia","description":"Gaia is a Node.js framework for building gRPC services with a focus on intuitive service definition, custom error handling, and shareable .proto files packaged as npm dependencies. Current version 3.1.7 supports both proto2 and proto3, integrates with Egg.js plugins, and provides optional RESTful API routing on top of gRPC. It distinguishes itself from raw gRPC by offering opinionated structure, built-in controller orchestration, and centralized proto management. Development appears sporadic with no recent releases.","status":"maintenance","version":"3.1.7","language":"javascript","source_language":"en","source_url":"git://github.com/kaelzhang/gaia","tags":["javascript","gaia","app","application","framework","grpc","server","client","protobuf"],"install":[{"cmd":"npm install gaia","lang":"bash","label":"npm"},{"cmd":"yarn add gaia","lang":"bash","label":"yarn"},{"cmd":"pnpm add gaia","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core gRPC implementation","package":"@grpc/grpc-js","optional":false},{"reason":"Plugins support","package":"egg-core","optional":true}],"imports":[{"note":"CJS-only, no ESM exports","wrong":"import { Server } from 'gaia'","symbol":"Server","correct":"const { Server } = require('gaia')"},{"note":"Default import does not exist","wrong":"import Client from 'gaia'","symbol":"Client","correct":"const { Client } = require('gaia')"},{"note":"Utility function for resolving proto packages","wrong":"","symbol":"resolvePackage","correct":"const { resolvePackage } = require('gaia')"}],"quickstart":{"code":"const path = require('path');\nconst { Server, Client } = require('gaia');\n\n// Start server\nconst root = path.join(__dirname, 'proto');\nconst server = new Server(root);\nserver.listen(50051);\n\n// Run client\n(async () => {\n  const client = new Client(root);\n  const { Greeter } = client.connect('localhost:50051');\n  const { message } = await Greeter.sayHello({ name: 'world' });\n  console.log(message); // Hello world\n})();","lang":"javascript","description":"Demonstrates creating a gRPC server and client with Gaia's intuitive API, loading proto files from a root directory."},"warnings":[{"fix":"Use destructuring to extract services: const { Greeter } = client.connect(host)","message":"Client.connect() returns service objects, not a client stub","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Replace server.kill() with await server.close()","message":"Server.kill() is deprecated; use Server.close()","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure .proto files are in a directory with package.json or use includeDirs","message":"Proto files must be part of an npm package to be importable","severity":"gotcha","affected_versions":">=3.0.0"},{"fix":"Upgrade your proto definition to be compatible with Gaia's loader","message":"Removed support for @grpc/proto-loader; uses internal loader","severity":"breaking","affected_versions":">=3.0.0"},{"fix":"Use CommonJS require()","message":"Requires Node.js >=10, no ESM support","severity":"gotcha","affected_versions":">=3.0.0"}],"env_vars":null,"search_vec":"'3.1.7':31 'api':45 'app':79 'appear':71 'applic':80 'build':8 'built':62 'built-in':61 'central':67 'client':84 'control':64 'current':29 'custom':18 'definit':17 'depend':28 'develop':70 'distinguish':52 'egg.js':39 'error':19 'file':24 'focus':13 'framework':6,81 'gaia':1,2,78 'grpc':9,50,56,82 'handl':20 'integr':37 'intuit':15 'javascript':77 'manag':69 'node.js':5 'npm':27 'offer':58 'opinion':59 'option':43 'orchestr':65 'packag':25 'plugin':40 'proto':23,68 'proto2':34 'proto3':36 'protobuf':85 'provid':42 'raw':55 'recent':75 'releas':76 'rest':44 'rout':46 'server':83 'servic':10,16 'shareabl':22 'sporad':72 'structur':60 'support':32 'top':48 'version':30","created_at":"2026-06-07T16:52:59.601863+00:00","updated_at":"2026-06-07T16:52:59.601863+00:00","problems":[{"fix":"Run 'npm install gaia'","cause":"Gaia not installed or import path incorrect","error":"Error: Cannot find module 'gaia'"},{"fix":"Use const { Client } = require('gaia')","cause":"Using default import instead of named import","error":"TypeError: Client is not a constructor"},{"fix":"Create a package.json in the proto directory or use { includeDirs } config","cause":"Proto root directory missing package.json","error":"Error: ENOENT: no such file or directory, open '/path/to/proto/package.json'"},{"fix":"Use a different port or kill the existing process","cause":"Port already in use","error":"Error: listen EADDRINUSE :::50051"}],"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":"https://github.com/kaelzhang/gaia#readme","github":"git://github.com/kaelzhang/gaia","docs":null,"changelog":null,"pypi":null,"npm":"gaia","openapi_spec":null,"status_page":null,"smithery":null,"categories":["devops"],"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}}