Convex Hono Generator

Generate Hono route registration from convex/**/http.ts. Each folder becomes a URL segment, so convex/admin/tasks/http.ts serves /admin/tasks. The generator writes the generated route implementation to convex/http.gen.ts and the Convex entrypoint to convex/http.ts.

Use it in a Convex project

In your Convex project, install the generator and its peer dependencies:

pnpm add convex hono convex-helpers
pnpm add -D @esauflores/convex-hono-generator

The npm package is scoped, but its executable is convex-hono-generator.

Create a Hono app in a nested http.ts and export it as the default. For example, convex/health/http.ts can contain:

import { Hono } from "hono";

const routes = new Hono();
routes.get("/", (c) => c.json({ status: "ok" }));

export default routes;

Run the generator from your Convex project when you add, remove, or move a route file:

pnpm exec convex-hono-generator generate

The command writes convex/http.gen.ts and creates convex/http.ts when it is missing. Run it again after changing the route folder structure, then run convex dev or convex deploy as usual. The CLI requires Node 20 or newer. Keep http.ts as the user-owned entrypoint when you need to compose additional routers:

import { HttpRouterWithHono } from "convex-helpers/server/hono";

import app from "./http.gen";
import otherRoutes from "./other/http";

app.route("/other", otherRoutes);

export default new HttpRouterWithHono(app);

Routes mount relative to the nearest parent http.ts. For example, the generator attaches convex/admin/comments/http.ts to convex/admin/http.ts with adminRoutes.route("/comments", commentsRoutes). It then mounts adminRoutes at /admin, so the child serves /admin/comments and shares the parent's middleware.

A folder named [id] mounts as :id. The generator ignores the root http.ts and http.gen.ts files, along with all folders whose names start with _, including _generated.

Run the example

The included convex/ project provides:

• CRUD routes for users, projects, tasks, comments, and tags.
• GET, POST, PATCH, and DELETE operations for each resource.
• Paginated list endpoints with ?limit=1 through ?limit=100 (default 100). Responses return a continueCursor; pass that value as ?cursor=... to fetch the next page.
• A public GET /health endpoint.
• Admin routes protected by the demo credential Bearer ok.

For this repository, generate the example routes and start the local Convex backend in one terminal:

pnpm convex:generate
pnpm convex:dev

In a second terminal, run the integration test:

pnpm test:local

pnpm test runs the generator and Hono tests without a backend. pnpm test:local checks CRUD through the local Convex HTTP endpoint in .env.local.