HonestJS

Appearance

Overview ​

Welcome to the HonestJS documentation! HonestJS is a modern, lightweight web framework for TypeScript and JavaScript, built on top of Hono.

INFO

Project Status HonestJS is in early development (pre-v1.0.0). The API may change between minor versions and some features are still in progress. We recommend caution before using it in production until v1.0.0 is released. Follow progress on GitHub or join the Discord.

What is HonestJS? ​

HonestJS provides a clean, decorator-based API for building web applications with:

  • Decorator-based Architecture: TypeScript decorators for Controllers, Services, and Modules
  • Dependency Injection: Simple yet powerful DI container for managing application components
  • Comprehensive Components System: Support for middleware, guards, pipes, and filters
  • API Versioning: Built-in support for API versioning with flexible versioning strategies
  • Application context: App-level typed key-value store so your app and plugins can share pipeline data by key without hard coupling
  • Plugin System: Extensible architecture with plugin support for custom functionality
  • MVC Support: Full-stack apps with Hono JSX views; use the mvc template (honestjs new my-app -t mvc) or see MVC
  • Error Handling: Comprehensive error handling with customizable exception filters
  • Route Management: Advanced routing with parameter binding, query parsing, and header extraction

Quick Start ​

Get up and running with HonestJS in minutes! Use the CLI (bun add -g @honestjs/cli then honestjs new my-app) or check our Getting Started guide for a complete tutorial. Or jump right in with this minimal example:

typescript
import 'reflect-metadata'
import { Application, Controller, Get, Module, Service } from 'honestjs'

@Service()
class AppService {
	helloWorld(): string {
		return 'Hello, World!'
	}
}

@Controller()
class AppController {
	constructor(private readonly appService: AppService) {}

	@Get()
	helloWorld(): string {
		return this.appService.helloWorld()
	}
}

@Module({
	controllers: [AppController],
	services: [AppService]
})
class AppModule {}

const { app, hono } = await Application.create(AppModule)
export default hono

Documentation Sections ​

Getting Started ​

Core Concepts ​

Components ​

  • Overview - Overview of the components system
  • Middleware - Request/response processing middleware
  • Guards - Authentication and authorization guards
  • Pipes - Data transformation and validation pipes
  • Filters - Exception handling filters

Features ​

  • Application context - App-level registry for sharing pipeline data by key (app and plugins)
  • Testing - Lightweight testing helpers for application, controller, and service tests
  • MVC Support - Model-View-Controller architecture
  • Plugins - Extending framework functionality
  • Helpers - Utility functions and helper methods

Framework Architecture ​

HonestJS is organized around several core concepts:

Application
├── Modules (organize components)
│   ├── Controllers (handle requests)
│   ├── Services (business logic)
│   └── Components (cross-cutting concerns)
│       ├── Middleware (request processing)
│       ├── Guards (authentication/authorization)
│       ├── Pipes (data transformation)
│       └── Filters (error handling)
└── Dependency Injection (automatic instantiation)

Key Features ​

Decorator-Based API ​

typescript
@Controller('users', { version: 1 })
class UsersController {
	@Get()
	@UseGuards(AuthGuard)
	@UsePipes(ValidationPipe)
	async getUsers(@Query('page') page?: string) {
		return await this.usersService.findAll({ page })
	}
}

Dependency Injection ​

typescript
@Service()
class UserService {
	constructor(private readonly db: DatabaseService) {}

	async findAll() {
		return await this.db.query('SELECT * FROM users')
	}
}

@Controller('users')
class UsersController {
	constructor(private readonly userService: UserService) {}
	// UserService is automatically injected
}

API Versioning ​

typescript
// Global version
const { app, hono } = await Application.create(AppModule, {
	routing: { version: 1 }
})
typescript
// Controller-specific version
@Controller('users', { version: 2 })
class UsersController {}
typescript
// Version-neutral routes
@Controller('health', { version: VERSION_NEUTRAL })
class HealthController {}

Component System ​

typescript
// Global components
const { app, hono } = await Application.create(AppModule, {
	components: {
		middleware: [new LoggerMiddleware({ level: 'info' })],
		guards: [AuthGuard],
		pipes: [ValidationPipe],
		filters: [HttpExceptionFilter]
	}
})
typescript
// Controller-level components
@Controller('users')
@UseMiddleware(LoggerMiddleware)
@UseGuards(AuthGuard)
class UsersController {}
typescript
// Handler-level components
@Controller('users')
class UsersController {
	@Get()
	@UseGuards(AdminGuard)
	@UsePipes(CustomPipe)
	getUsers() {}
}

Server-Side Rendering ​

typescript
import { Controller, Get, Layout } from 'honestjs'

@Controller('pages')
class PagesController {
	@Get('home')
	home() {
		// Layout returns a Response (from hono/html) - return it directly
		return Layout({
			title: 'Home - My App',
			description: 'Welcome to our application',
			children: '<h1>Welcome to My App</h1>'
		})
	}
}

Installation ​

bash
bun add honestjs hono reflect-metadata
bash
npm install honestjs hono reflect-metadata
bash
pnpm add honestjs hono reflect-metadata
bash
yarn add honestjs hono reflect-metadata

For detailed setup instructions, see our Getting Started guide.

Help ​

  • FAQ - Answers to common questions about setup, DI, routing, and more
  • Troubleshooting - Edge cases, error messages, and fixes

Community and Support ​

License ​

HonestJS is licensed under the MIT License. See the LICENSE file for details.

Start building with HonestJS today! Check out the Getting Started guide for a detailed tutorial.

Released under the MIT License.

Copyright © 2025-present Orkhan Karimov & HonestJS contributors.