6.0.0 • Public • Published

Build Status Coverage


The manager to wrap grpc services and hold .proto files.

  • Handle Custom Errors gRPC does NOT provide an formal way to handle errors, even lack of documentation, while gaea will do it for you.
  • Manage .proto files gaea allows us to share proto files between server and clients. gaea shares gPRC protobuf files by wrapping them into an npm package and publishing the npm tarball to npm registry.
  • Eggjs compatible plugins gaea supports to use egg plugins to extend your applications.
  • Restful API service made easy gaea provides a convenient way to define restful API routings upon the existing gRPC services.


$ npm i gaea


const {
  Server, Client 
= require('gaea')
const root = path.join(__dirname, 'example')

To make better understanding the usage of gaea, the example below is based on the demo in the example/hello directory.

Start server:

new Server(root).listen(50051)

Run client:

const {
  // service Greeter 
= new Client(root).connect('localhost:50051')
const run = async () => {
  const {message} = await Greeter.sayHello({name: 'world'})
// Hello world


new Client(root, clientConfig?)

Creates the gaea client.

  • root path the root path to load the client from
  • clientConfig? BaseConfig client configuration. If not specified, gaea will load configuration from ${root}/config.js
interface BaseConfig {
  // Tells `gaea` which properties of error should be
  // - collected, serialized and transmitted to the clients.
  // - or deseriialized from server
  // `error_props` defaults to `['code', 'message']`
  error_props: Array<string>
  // specifies where to load proto files.
  proto_root: string
  // Proto filenames inside `proto_root`.
  // If not specified, gaea will use all `.proto` files inside `proto_root`.
  protos?: Array<string>


Connects to the gRPC server and returns the service methods

  • host string the server host to connect to which includes the server hostname and port and whose pattern is <hostname>:<port>

new Server(root, serverConfig?)

  • root path the root path to load the server from
  • serverConfig? ServerConfig server configurations. If not specified, gaea will load configuration from ${root}/config.js
interface ServerConfig extends BaseConfig {
  plugins: Array<Plugin>
  services: Services
interface Package {
  // The root path of the package
  path?: string
  // The package name of the package
  package?: string
  // Either path or package should be defined.
interface Plugin extends Package {
  // Configurations for the plugin
  config: object
interface Service extends Package {
  // the host param of `client.connect(host)`
  host: string
interface Services {
  [name: string]: Service
const g = gaea({
  // if the server throws an `error`, gaea will collect
  // - `error.code`,
  // - `error.message`
  // - `error.stack`,
  // and send them to its clients, while other properties will be omitted.
  error_props: ['code', 'message', 'stack'],
  proto_root: '/path/to/example/proto'
  // and read all .proto files

server.listen(port): void

  • port number the port which gRPC server will listen to.

Start the gaea server.



If we have a foo package in a proto file, and inside the foo package there is a Bar service, then we must put a foo/Bar.js file in /path/to/example/service/.

And if there is a Baz rpc method in the Bar service, we must set a Baz function as one of the exports of the foo/Bar.js. The Baz function might have one argument(or no arguments) which accepts the data from the client.

Or there will be errors.

Besides, if there is a Quux service which not in any package, we should just put a Quux.js file in /path/to/example/service/.

Package Sidebar


npm i gaea

Weekly Downloads






Unpacked Size

24.7 kB

Total Files


Last publish


  • kael