3.1.7 • Public • Published

    Build Status Coverage

    gaia (for node.js)

    Gaia, the very framework to make gRPC services. Gaia defines a definitely intuitive way to write gRPC services.

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

    gaia supports both proto2 and proto3.


    $ npm i gaia

    Table of Contents


    const {
    = require('gaia')
    const root = path.join(__dirname, 'example', 'hello')

    To make better understanding the usage of gaia, the example below is based on the demo in the example/node/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)

    Creates the gaia client.

    • root path the root path to load the client from


    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
    interface ServerConfig {
      // Defines where to load controllers
      controller_root?: string = 'controller'
      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

    server.listen(port): this

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

    Start the gaia server.


    Forcibly shut down the gRPC server

    await server.close()

    Gracefully shut down the server

    resolvePackage(id: string): string

    • id string package id

    Returns the root path of the package

    new Client(resolvePackage('foo')).connect(host)

    How gaia makes .proto files sharable and portable?

    gaia takes full advantage of npm packages to share proto files.

    A minimun gaia service portable, as well as service hello or package hello, could be:

      |-- proto/
      |       |-- hello.proto
      |-- package.json

    And in proto/hello.proto:

    syntax = "proto3";
    service Greeter {
      rpc SayHello (HelloRequest) returns (HelloReply) {}
    message HelloRequest {
      string name = 1;
    message HelloReply {
      string message = 1;


      "name": "hello",
      "gaia": {

    The the optional field "gaia" of package.json follows the schema:

    interface FieldGaia {
      // Tells `gaia` which properties of error should be
      // - collected, serialized and transmitted to the clients.
      // - or deseriialized from server
      // `errorProps` defaults to `['code', 'message']`
      // if the server throws an `error`, by default, gaia will collect
      // - `error.code`,
      // - `error.message`
      // and send them to its clients, while other properties will be omitted.
      errorProps?: Array<string> = ['code', 'message']
      // Specifies where to load proto files.
      // `protoPath` should be a relative path to `root`
      protoPath?: string = 'proto'
      // Proto filenames inside `protoPath`.
      // If not specified, gaia will search all `*.proto` files inside `protoPath`.
      protos?: Array<string> | string = '*.proto'
      // See section #import-proto-files-from-hello below
      protoDependencies?: Array<string> = []

    Apparently, package hello has everything we need to create a client agent for service hello.

    And package hello is language-independent which only contains proto files and client configurations.

    Create the client of hello

    Assume that we have a new project foo, and we npm install hello.

      |-- proto/
      |        |-- foo.proto
      |-- node_modules/
      |              |-- hello/
      |-- package.json

    Then if the hello service is already running on port 8000, we could create a hello client by following lines:

    const {Client} = require('gaia')
    const {Greeter} = new Client('/path/to/foo/node_modules/hello').connect('localhost:8000')

    Import .proto files from hello

    Since project foo, as we introduced above, has a dependency hello, we could import .proto files from package hello.

    in /path/to/foo/proto/foo.proto:

    syntax = "proto3";
    // We could install a package and import things from it
    // as well as we do in JavaScript es modules. Oh yeah! 😆
    import "hello/proto/hello.proto"
    service FooGreeter {
      // We could reuse message types from package `hello`
      rpc SayHello (HelloRequest) returns (HelloReply) {}

    In order to do that, we need to declare that hello is a gaia dependency of foo by adding some fields in package.json:

      "name": "foo",
      "gaia": {
        // So that we could import .proto files from package `hello`
        "protoDependencies": [
          // We have to add "hello" here.
      "dependencies": {
        // This is generated by `npm install`
        "hello": "^1.0.0"

    And gaia will manage the --proto_paths (includeDirs) for you, so that gRPC Protobuf Loader will know where to search and import .proto files

    More about includeDirs

    gaia recursively parses the protoDependencies of project foo, and its protoDependency's protoDependencies to generate the options.includeDirs option for @grpc/proto-loader

    How to Write a gaia Server

    Take the project hello which introduced above for example.

    Since we define a Greeter service in hello.proto, we must implement the corresponding controller by ourselves.

    Service controllers should be defined in directory /path/to/hello/controller which can be changed with by config controller_root.

    We must provide a Greeter.js in that directory.

      |-- controller/
      |            |-- Greeter.js

    in Greeter.js, there should be an async/sync method named SayHello in exports because we defined a SayHello rpc method in service Greeter

    exports.sayHello = ({name}) => ({
      message: `Hello ${name}`

    Packages and name resolution

    First the innermost package scope is searched, then the next-innermost, and so on, and at last the service name.

    Assume that we have the following protocol buffer.

    service Baz {
      rpc Quux (Req) returns (Res) {}

    Then in directory controller_root, we need to create a JavaScript file foo/bar/Baz.js whose exports has a Quux method.

    this object of the controller methods

    There are several properties could be access by this object of the controller methods.

    Reusing other controllers

    We could access other controller methods by


    For example, we could access the Quux method by

    exports.OtherMethodsOfSomeService = async function (request) {
      const data = await
      // ...
      return something

    Using external services

    If we provide for server

    new Server('/path/to/service/foo', {
      services: {
        hello: {
          // 'hello' is a gaia server
          package: 'hello'

    Then, client of the service 'hello' could be accessed from the service controller of foo by:

    exports.Quux = async function ({name}) {
      const {message} = await this.service.hello.SayHello({name})
      return {
        property: message

    Using plugins




    npm i gaia

    DownloadsWeekly Downloads






    Unpacked Size

    33.3 kB

    Total Files


    Last publish


    • avatar