Hono Gateway Core (@engblock/hono-gateway-core)

Core library for building flexible, type-safe micro-frontend or micro-service gateways using Hono. This library provides the foundational components to route incoming requests based on URL prefixes to different handlers, supporting both direct function calls (monorepo style) and HTTP forwarding (e.g., Cloudflare Workers Service Bindings).

Overview

In modern web architectures, it's common to split applications into smaller, independently deployable units (micro-frontends or micro-services). A gateway acts as the single entry point, routing requests to the appropriate downstream service or rendering module.

hono-gateway-core simplifies the creation of such gateways within the Hono framework by providing:

1. A Gateway Factory (createGateway): Sets up a Hono application with core routing logic.
2. An Abstraction Layer (MicroAppHandler): Decouples the gateway from the specific mechanism used to handle the request (direct call vs. HTTP fetch).
3. Concrete Handler Implementations:
   • DirectCallHandler: For invoking local ssr functions directly (ideal for monorepos).
   • HttpFetchHandler: For forwarding requests to other HTTP endpoints or Cloudflare Worker Service Bindings.
4. Type Safety: Leverages TypeScript for robust development.

Core Concepts

• Gateway: The main Hono application instance created by createGateway. It intercepts requests matching patterns like /:appName/* and uses the configuration to find the correct handler.
• MicroAppHandler: An interface defining the contract for handling a request delegated by the gateway. The key method is handle(c: Context): Promise<Response>, which must return a complete Response object.
• DirectCallHandler: An implementation of MicroAppHandler that takes a module conforming to the DirectRenderApp interface (having an ssr(c: Context): Promise<string> | string method). It calls the ssr method and wraps the resulting HTML string in a Response.
• HttpFetchHandler: An implementation of MicroAppHandler that forwards the incoming request to another HTTP service. It can be configured to use Cloudflare Worker Service Bindings (type: 'cf_binding') or a standard base URL (type: 'url'). It returns the Response received from the downstream service.
• HandlerConfigFactory: A function (c: Context<GatewayEnv>) => HandlerConfig provided to createGateway. It's responsible for creating the mapping between URL prefixes (e.g., "profile") and their corresponding MicroAppHandler instances. Crucially, it receives the Hono Context (c), allowing access to environment variables (c.env) needed for configuring handlers (like HttpFetchHandler with service bindings).

Features

• Flexible Delegation: Supports both direct function invocation and HTTP forwarding out-of-the-box.
• Type-Safe: Built with TypeScript, providing strong typing for configuration and context.
• Extensible: Easily create custom MicroAppHandler implementations for other delegation strategies.
• Hono Integration: Built on top of the fast and lightweight Hono framework.
• Environment-Aware Configuration: Access environment variables/bindings within the configuration factory.
• Testability: The handler abstraction makes individual routing strategies easier to test in isolation.

Installation

# Using npm
npm install @engblock/hono-gateway-core hono

# Using yarn
yarn add @engblock/hono-gateway-core hono

# Using pnpm
pnpm add @engblock/hono-gateway-core hono