HonoX: a file-based meta-framework on top of Hono, Vite and your own JSX renderer

The gap HonoX fills between a router and a website

Hono is a small HTTP framework. You register routes in code, compose middleware, and return responses. That is enough for an API, but a website needs more: a directory convention for pages, a way to wrap every page in an HTML shell, a not-found page, an error page, and a story for client-side JavaScript that does not ship the whole app to the browser. HonoX is the layer that supplies those pieces while leaving Hono underneath.

The README describes it as a "simple and fast meta-framework for creating full-stack websites or Web APIs", built on Hono, Vite and UI libraries. The target reader is a TypeScript developer who already knows Hono and does not want to learn a second request model. Everything you know about Hono middleware still applies, because createApp() returns a Hono instance. The README notes you can call showRoutes() from hono/dev on it, which is the same debugging helper Hono users already have.

The project was formerly called Sonik, and the README states it is in the "alpha stage". That word matters more than any feature list. The version in package.json is 0.1.61, and the README links to the semantic versioning rule for zero-version software, which permits breaking changes inside the same major version. Treat every 0.1.x bump as a release that may require edits.

How routing, renderers and islands fit together

The mechanism is convention over a directory named app. Files under app/routes become URLs. The README gives a sample tree where app/routes/index.tsx matches /, app/routes/about/[name].tsx matches /about/:name, and app/routes/merch/[...slug].tsx matches /merch/:category, /merch/:category/:item and /merch/:category/:item/:variant. Underscore-prefixed files are special: _404.tsx is the not-found handler, _error.tsx is the error handler, and _renderer.tsx defines the renderer.

There are three ways to write a route, and they can coexist. The first is createRoute() from honox/factory, which returns an array of Handler or MiddlewareHandler values; a default export handles GET, and named exports such as POST, PUT and DELETE handle other methods. The second is exporting a plain Hono instance, which the README shows for a JSON endpoint. The third is exporting a component that returns JSX directly.

The renderer is the part worth understanding before you write code. It is a middleware that calls c.setRender(), and the README's example uses jsxRenderer from hono/jsx-renderer. Because _renderer.tsx applies to its own directory and below, app/routes/posts/_renderer.tsx wraps only the routes under posts. That is a real structural difference from frameworks with a single root layout, and it is how you give a blog section a different HTML shell from the marketing pages without conditional logic.

Islands are the client-side story. The README says JavaScript is hydrated only for an island component, and the client example places the entry at app/client.ts with island components under app/islands. The README also states that you can bring your own renderer rather than using hono/jsx, which it abbreviates as BYOR. That is the clearest signal of the project's intent: it provides the routing and build plumbing, not a rendering religion.

Installing HonoX and getting a first route running

The package is published as honox on npm, and Hono is a peer you install alongside it. The README gives two entry points. For an existing project:

npm install hono honox

For a new project, the README points at the hono-create command and says to choose the x-basic option with the arrow keys:

npm create hono@latest

Once the project exists, the minimum Vite configuration is a single plugin, as shown in the README:

import { defineConfig } from 'vite'
import honox from 'honox/vite'

export default defineConfig({
  plugins: [honox()],
})

A server entry file is required at app/server.ts. The README says this file is first called by Vite during development or build, and that createApp() returns a Hono instance:

// app/server.ts
import { createApp } from 'honox/server'
import { showRoutes } from 'hono/dev'

const app = createApp()

showRoutes(app)

export default app

With those three files in place, add a first page. The README's example uses createRoute() and c.render():

// app/routes/index.tsx
import { createRoute } from 'honox/factory'

export default createRoute((c) => {
  return c.render(
    <div>
      <h1>Hello!</h1>
    </div>
  )
})

What you should see: the dev server prints the registered routes because of showRoutes(app), and visiting the root path renders the heading. Note that c.render() only produces a full HTML document once a renderer is defined. The README's renderer example lives at app/routes/_renderer.tsx and uses jsxRenderer from hono/jsx-renderer, and it also requires a ContextRenderer type declaration in app/global.d.ts. If you skip the renderer, you have a route that calls a method whose output shape you have not declared.

Where HonoX is the wrong tool

The alpha label is not decoration. The README states plainly that breaking changes are introduced within the same major version, and the release history shows a steady cadence of 0.1.x versions. If your project needs a frozen API and a long support window, this is the wrong dependency, and no amount of Hono familiarity changes that.

There is a second constraint that is easy to miss. HonoX does not ship a renderer of its own; the README's basic guide uses hono/jsx, and BYOR is listed as a feature. That means the HTML layer, the type declaration for ContextRenderer and the client entry are all yours to assemble. A framework that hands you a renderer and a data-loading convention will get a small site running faster than this, even if it gives you less control later.

A third case: if you only need JSON endpoints, HonoX adds a Vite build, a file-system router and a renderer concept you will never use. Plain Hono already handles that, and the README's own second routing style, exporting a Hono instance from a file, is the same code you would write without the meta-framework. The README does not document any rollback or migration tooling for route conventions, so if you later change how routes are laid out, the work is manual. It also does not document a compatibility matrix for Vite versions, so pinning matters.

HonoX against TanStack Router and plain Hono

The realistic alternatives differ in where routing lives. Plain Hono keeps routes in code: you call app.get('/about/:name', handler) and the URL structure is visible in one file. HonoX moves that structure into the filesystem, which scales better once there are dozens of pages and per-section layouts, and worse when you want to see every route at a glance. The README's showRoutes(app) call is the mitigation, and it is a debugging aid rather than a route manifest.

TanStack Router is the other comparison the search data surfaces. It is a client-side router with typed route definitions and a strong focus on type-safe navigation and data loading in a single-page application. HonoX is server-first: the README describes fast SSR and islands hydration, where only island components get JavaScript. If your application is a dashboard that lives in the browser and talks to an API, TanStack Router fits that shape. If your application is mostly server-rendered pages with a few interactive widgets, HonoX's islands model keeps the bundle small by construction.

The Hono versus Express comparison that people search for is a different axis and does not really apply here, because HonoX does not replace Hono. It sits on top of it. Choosing HonoX is a decision about routing convention and rendering, not about the HTTP layer, and the README makes that explicit by pointing at Hono's middleware as available to you.

Maintenance, releases and what the MIT licence leaves you

The repository is not archived. The last push was on 2026-08-18, and the most recent release, v0.1.61, is dated the same day, so the project is being published. The two prior releases, v0.1.60 and v0.1.59, landed on 2026-07-25 and 2026-07-10. That is a release roughly every two to three weeks across that window, which is a real upgrade cost: you should expect to read release notes before bumping, and the README's warning about breaking changes within a major version means a patch-level bump is not automatically safe.

The upgrade mechanics are visible in package.json. The published artifact is the dist directory, built by tsdown, and the exports map exposes subpaths including ./server, ./factory, ./client and ./constants. If you import from a subpath that moves, your build breaks at resolution time rather than at runtime, which is at least a loud failure.

The licence is MIT. That permits commercial use, modification and redistribution provided the copyright notice and permission notice are included. It also means there is no warranty, and no obligation on the maintainers to keep the alpha API stable. This is not legal advice; if your organisation has a policy on alpha-stage dependencies, the version number and the README's own note are the facts to put in front of whoever decides.

Editorial conclusion

Adopt HonoX if your team already runs Hono middleware and wants file-based routes, per-directory renderers and islands without a second server runtime. Do not adopt it if you need a stable API surface, because the README states breaking changes arrive within the same major version and the current line is 0.1.61. Before committing, verify three things in your own project: that a custom _renderer.tsx in a nested route directory overrides the root one as the README describes, that your chosen renderer works through the jsxRenderer middleware, and that the honox/vite plugin builds your app with the Vite version you have pinned.

Frequently asked questions

Official sources

1. honojs/honox on GitHub
2. License: MIT
3. Project website
4. README
5. Releases