hono-forge

library3.0.0jsnpmunverified

NestJS-style decorator-based framework for Hono (v3.0.0) — controller routing, dependency injection, guards, SSE, WebSocket, channels, and OpenAPI auto-generation. Ships TypeScript types, uses TC39 Stage 3 decorators (no experimentalDecorators, no reflect-metadata). Active development, major release v3 uses ESM-only; requires Hono >=4 and zod >=4 as peer dependencies. Compared to NestJS, it is lighter and Hono-native; compared to plain Hono, it adds DI and decorator-driven structure without heavy abstractions. Release cadence is irregular but feature-rich with each major bump.

devops

npm install hono-forge

package ↗

INSTALL

IMPORT

SIG · HONO-FORGE

hono-forge

devopsjavascriptv3.0.0

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Controller

✓ import { Controller } from 'hono-forge'

✗ const { Controller } = require('hono-forge')

hono-forge is ESM-only since v3; CommonJS require() will fail.

Get

✓ import { Get } from 'hono-forge'

Named export; also Post, Put, Patch, Delete, Head, Options, All.

Injectable

✓ import { Injectable } from 'hono-forge'

✗ import { Injectable } from 'hono-forge/Injectable'

Injectable is a top-level export, not a subpath.

HonoRouteBuilder

✓ import { HonoRouteBuilder } from 'hono-forge'

✗ import { RouteBuilder } from 'hono-forge'

The class is named `HonoRouteBuilder` since v2; `RouteBuilder` was removed.

OpenAPIGenerator

✓ import { OpenAPIGenerator } from 'hono-forge'

Added in v2; generates OpenAPI spec from decorators and mounts Scalar UI.

require('hono-forge')

✓ import { Controller } from 'hono-forge'

✗ const honoForge = require('hono-forge')

ESM-only package; CommonJS require() throws ERR_REQUIRE_ESM.

Shows basic controller with dependency injection, GET/POST routes, Zod validation, and route building.

import { Hono } from 'hono'; import type { Context } from 'hono'; import { Controller, Get, Post, Injectable, HonoRouteBuilder, } from 'hono-forge'; import { z } from 'zod'; const CreateUserSchema = z.object({ name: z.string(), email: z.string().email() }); @Injectable() class UserService { getAll() { return [{ id: 1, name: 'Alice' }]; } create(data: { name: string; email: string }) { return { id: 2, ...data }; } } @Controller('/users') @Injectable([UserService]) class UserController { constructor(private userService: UserService) {} @Get() list() { return this.userService.getAll(); } @Post() async create(c: Context) { const body = await CreateUserSchema.parseAsync(await c.req.json()); return this.userService.create(body); } @Get('/:id') getOne(c: Context) { return { id: c.req.param('id') }; } } const app = new Hono(); app.route('/', HonoRouteBuilder.build(UserController)); export default app;

Debug

Known issues

breakingESM-only module: CommonJS require() will fail with ERR_REQUIRE_ESM.

fix

Use import syntax or ensure your project is configured for ESM (type='module' in package.json).

affects: >=3.0.0

breakingv3 dropped support for experimentalDecorators; only TC39 Stage 3 decorators are supported.

fix

Remove experimentalDecorators and useTypeScript 5.0+ with target: 'ESNext'.

affects: >=3.0.0

breakingHonoRouteBuilder import path changed; subpath exports may have moved.

fix

Use `import { HonoRouteBuilder } from 'hono-forge'` instead of `from 'hono-forge/builder'`.

affects: >=2.0.0

deprecated`RouteBuilder` export renamed to `HonoRouteBuilder`.

fix

Use `HonoRouteBuilder` or upgrade to v3 which only exports `HonoRouteBuilder`.

affects: >=2.0.0 <3.0.0

gotchaHandler functions receive `c: Context` from Hono, not a special argument; do not expect `@Param()` or similar parameter decorators.

fix

Access request data via `c.req.param()`, `c.req.query()`, etc.

affects: >=1.0.0

gotchaDependency injection requires `@Injectable()` on both the service and the controller; constructor injection only works for classes decorated with `@Injectable`.

fix

Ensure every class that participates in DI has the `@Injectable()` decorator.

affects: >=1.0.0

Errors

Common errors & fixes

Cannot use import statement outside a module

Project is using CommonJS (type: 'commonjs' or no type field) with ESM-only hono-forge v3.

fix

Set 'type': 'module' in package.json or rename .js files to .mjs.

ERR_REQUIRE_ESM: require() of ES Module not supported

Using require('hono-forge') in a CommonJS context.

fix

Switch to import syntax or use dynamic import(): const m = await import('hono-forge').

Property 'build' does not exist on type 'typeof import(...)'

Importing from wrong path (e.g., 'hono-forge/builder') or using older version where RouteBuilder was the name.

fix

Use `import { HonoRouteBuilder } from 'hono-forge'` and call HonoRouteBuilder.build().

The decorator '@Injectable' is not permitted here

TypeScript project uses experimentalDecorators: true with TC39 decorators in hono-forge v3.

fix

Set compilerOptions.experimentalDecorators to false and target to ESNext.

Upgrade

Version history

3.0.0latest on npm

Audit

Dependencies

honorequiredCore HTTP framework; hono-forge decorators require Hono >=4

zodrequiredRequired for validation decorators and OpenAPI generation (schema inference); peer dependency >=4

Agent activity

6 hits · last 30 days

node

Resources

packagehono-forge ↗