@dendrell/react-router-hono

Hono adapter for React Router server builds.

It wraps a React Router server build with a Hono app, optionally serves the built client files, and returns a runner function that works with node-cluster-serve or direct startup code.

This package is for production-style server builds. It is not a Hono development server.

This library also assumes that you handle HTTP response body compression in an upper layer (e.g. Nginx), so it does not handle that for you.

Note: RSC Server Builds are not supported yet, but any PRs for that are welcome as soon as the feature becomes stable in React Router.

Install

pnpm add @dendrell/react-router-hono

If you want to use the cluster runner:

pnpm add node-cluster-serve

Quick start

// server.ts
import { createServerRunner } from '@dendrell/react-router-hono'

const serverBuildFile = new URL('../server/index.js', import.meta.url)
export default createServerRunner(serverBuildFile, {
  // app: existingHonoApp, // Optional, if you want to reuse an existing instance
  serveClientAssets: true,
  assetMaxAge: '1y',
  publicFileMaxAge: '1h',
  serverTimingHeader: true,
  origin: process.env.PUBLIC_ORIGIN,
  prepare: async (app) => {
    app.get('/api/hello', (c) => c.json({ message: 'Hello World' }))
  },
})

Run it with node-cluster-serve:

node-cluster-serve ./server.ts --port 3000 --workerCount 4

Or run it directly:

import { createServerRunner } from '@dendrell/react-router-hono'

let run = createServerRunner('./build/server/index.js', {
  serveClientAssets: true,
})

await run({
  mode: 'production',
  host: process.env.HOST ?? '0.0.0.0',
  port: Number(process.env.PORT ?? 3000),
})

API

createServerRunner(serverBundleFile, options)

import type { Hono } from 'hono'
import type { ServeFunction, ServerMode } from 'node-cluster-serve'

type CreateServerRunnerOptions = {
  app?: Hono
  serveClientAssets: boolean
  assetMaxAge?: string
  publicFileMaxAge?: string
  logRequests?: boolean
  serverTimingHeader?: boolean
  prepare?: (app: Hono) => Promise<void>
  mode?: ServerMode
  port?: number
  host?: string
  origin?: string | URL
}

declare function createServerRunner(
  serverBundleFile: string | URL,
  options: CreateServerRunnerOptions,
): ServeFunction

serverBundleFile

• Path or file: URL to the React Router server build module.
• String paths are resolved from process.cwd().

options.serveClientAssets

• Enables static file serving from build.assetsBuildDirectory.
• Static URLs are scoped to build.publicPath.
• Requests under <publicPath>/assets/* get immutable cache headers.

options.assetMaxAge

• Cache age for files under <publicPath>/assets/*.
• Defaults to 1y.

options.publicFileMaxAge

• Cache age for other files served from build.assetsBuildDirectory.
• Defaults to 1h.

options.logRequests

• Logs METHOD pathname status - duration ms to console.log.

options.serverTimingHeader

• Adds Server-Timing: total;dur=<ms> to the React Router response before it is returned.

options.prepare(app)

• Async hook for registering middleware or routes before listen().

options.mode, options.port, options.host

• Optional overrides for values normally provided by the runner.
• If host is omitted, the adapter falls back to localhost.

options.origin

• Canonical origin used to build the Web Request passed to React Router.
• Useful behind proxies, TLS termination, or any deployment where the bound listen address is not the public origin.
• If omitted, the adapter falls back to the resolved host and port.

options.app

• Hono app instance to use for the server.
• If omitted, a new Hono app is created.

Behavior

• React Router requests are passed through as standard Web Request objects.
• React Router Response bodies are streamed back through Hono.
• Static file paths are normalized and constrained to stay inside the configured asset root.
• Missing static files fall through to the React Router request handler.

Notes

• createServerRunner does not manage worker processes itself.
• The server build module is imported dynamically at runtime.
• When deploying behind a reverse proxy, set origin to the public URL your React Router handlers should use as the request origin.

License

MIT