@openreachtech/renchan-express

Express bindings for renchan: route classes, and a base server builder that assembles an Express application out of an engine and a routes builder.

Concept

A server built on this package is split into three parts.

| part | responsibility | provided by | | :-- | :-- | :-- | | engine | holds the config, and collects the middleware and the Express settings | the application | | routes builder | produces the routes the server answers on | the application | | server builder | assembles the two into an Express application and an HTTP server | BaseExpressServerBuilder, derived by the application |

What kind of server it is — JSON-RPC, RESTful API, GraphQL — is settled by the routes builder a derived server builder names. The server builder itself knows nothing about it.

BaseExpressServerBuilder is the one place express and http are reached through, so that a major version of either is answered in a single file.

Installation

Requires Node.js 20.x or later (the CI builds against the current LTS).

npm install @openreachtech/renchan-express

It is an ES module ("type": "module"); import it with ESM import syntax.

express ^4.22.3 and @types/express ^4.17.25 are peer dependencies. The application provides them.

Usage

import express from 'express'

import {
  BaseExpressServerBuilder,
  GetMethodExpressRoute,
} from '@openreachtech/renchan-express'

// The engine: config, middleware and Express settings.
class AlphaServerEngine {
  static async createAsync () {
    return new this()
  }

  get config () {
    return {}
  }

  collectMiddleware () {
    return [
      express.json(),
    ]
  }

  collectExpressSettings () {
    return {
      'trust proxy': true,
    }
  }
}

// The routes builder: the routes the server answers on.
class AlphaRoutesBuilder {
  constructor ({
    engine,
  }) {
    this.engine = engine
  }

  static async createAsync ({
    engine,
  }) {
    return new this({
      engine,
    })
  }

  buildRoutes () {
    return [
      GetMethodExpressRoute.create({
        path: '/health',
        handlers: [
          (req, res) => {
            res.json({
              status: 'ok',
            })
          },
        ],
      }),
    ]
  }
}

// The server builder: names the routes builder, and nothing else.
class AlphaExpressServerBuilder extends BaseExpressServerBuilder {
  static get RoutesBuilderCtor () {
    return AlphaRoutesBuilder
  }
}

const serverBuilder = await AlphaExpressServerBuilder.createAsync({
  EngineCtor: AlphaServerEngine,
})

serverBuilder.buildHttpServer()
  .listen(3000)

The shapes the engine and the routes builder have to take are declared as ExpressType.ServerEngine and ExpressType.RoutesBuilder in types/express-type.d.ts.

API

API reference

How the server is assembled

#buildHttpServer() runs the following steps in order.

1. Apply the settings the engine collects to the Express application. Express reads its settings when the first route is mounted, so this comes before any mounting.
2. Collect one middleware route carrying every handler the engine collects.
3. Collect the routes the routes builder produces.
4. Mount the middleware route, then the other routes, onto the Express application.
5. Hand the mounted application to #buildServerRootApp(), which returns it unchanged unless a derived class overrides it.
6. Create an HTTP server from what step 5 returns. The server is returned without listening.

Contribution

Bug reports, feature requests, and code contributions are welcome.

Feel free to contact us through GitHub Issues.

git clone https://github.com/openreachtech/renchan-express.git
cd renchan-express
npm install
npm run lint
npm test

License

This project is released under the Apache License 2.0.

For more details, please see in the LICENSE file.

Developer

Open Reach Tech Inc.

Copyright

© 2026 Open Reach Tech Inc.