Cursor / Agent skills

Install the Honest skill so your editor agent (e.g. Cursor) can use Honest-specific guidance:

bunx skills add https://github.com/honestjs/skills --skill honest

See honestjs/skills for details.

🚨 Early Development Warning 🚨

Honest is currently in early development (pre-v1.0.0). Please be aware that:

• The API is not stable and may change frequently
• Breaking changes can occur between minor versions
• Some features might be incomplete or missing
• Documentation may not always be up to date

We recommend not using it in production until v1.0.0 is released.

⚠️ Documentation is not yet complete ⚠️

If you find any issues or have suggestions for improvements, please open an issue or submit a pull request. See CONTRIBUTING.md for how to contribute and CODE_OF_CONDUCT.md for community guidelines.

Quick Start

bun add -g @honestjs/cli
honestjs new my-project    # alias: honest, hnjs; interactive template picker
cd my-project
bun dev

Templates: blank (minimal), barebone (modules + services — best for APIs), mvc (full-stack with Hono JSX views). Use -t barebone -y to skip prompts.

See Getting Started on honestjs.dev for the full tutorial, and FAQ / Troubleshooting for common questions and edge cases.

Features

• 🚀 High performance — Built on Hono for maximum speed and minimal overhead.
• 🏗️ Familiar architecture — Decorator-based API inspired by NestJS; TypeScript-first.
• 💉 Dependency injection — Built-in DI container for clean, testable code and automatic wiring.
• 🔌 Plugin system — Extend the app with custom plugins, middleware, pipes, and filters. Plugins run in options.plugins order; wrapped entries may attach preProcessors / postProcessors and optional name for diagnostics.
• 🛣️ Advanced routing — Prefixes, API versioning, and nested route organization.
• 🛡️ Request pipeline — Middleware, guards, pipes, and filters at app, controller, or handler level.
• 🧪 Lightweight testing harness — Helpers for application, controller, and service-level tests.
• 🧭 Startup guide mode — Actionable diagnostics hints for startup failures.
• 📝 TypeScript-first — Strong typing and great IDE support out of the box.
• 🖥️ MVC & SSR — Full-stack apps with Hono JSX views; use the mvc template or the docs.

In code

import 'reflect-metadata'
import { Application, Controller, Get, Module, Service } from 'honestjs'
import { LoggerMiddleware } from '@honestjs/middleware'
import { AuthGuard } from '@honestjs/guards'
import { ValidationPipe } from '@honestjs/pipes'
import { HttpExceptionFilter } from '@honestjs/filters'
import { ApiDocsPlugin } from '@honestjs/api-docs-plugin'

@Service()
class AppService {
	hello(): string {
		return 'Hello, Honest!'
	}
}

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

	@Get()
	hello() {
		return this.appService.hello()
	}
}

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

const { app, hono } = await Application.create(AppModule, {
	startupGuide: { verbose: true },
	debug: {
		routes: true,
		plugins: true,
		pipeline: true,
		di: true,
		startup: true
	},
	logger: myLogger,
	strict: { requireRoutes: true },
	deprecations: { printPreV1Warning: true },
	container: myContainer,
	hono: {
		strict: true,
		router: customRouter
	},
	routing: {
		prefix: 'api',
		version: 1
	},
	// Components: use class (e.g. AuthGuard) or instance (e.g. new LoggerMiddleware()) to pass options
	components: {
		middleware: [new LoggerMiddleware()],
		guards: [AuthGuard],
		pipes: [ValidationPipe],
		filters: [HttpExceptionFilter]
	},
	plugins: [
		new RPCPlugin(),
		new ApiDocsPlugin(),
		{
			plugin: MyPlugin,
			name: 'core',
			preProcessors: [pre],
			postProcessors: [post]
		},
		{ plugin: MetricsPlugin, name: 'metrics' }
	],
	onError: (err, c) => c.json({ error: err.message }, 500),
	notFound: (c) => c.json({ error: 'Not found' }, 404)
})

export default hono

Controllers, services, and modules are wired by decorators; use guards for auth, pipes for validation, and filters for error handling. See the documentation for details.

Runtime Metadata Isolation

Decorator metadata is still collected globally, but each application instance now runs on an immutable metadata snapshot captured during startup. This prevents metadata mutations made after bootstrap from changing behavior in already-running applications.

Plugin order

Plugins run in the order they appear in options.plugins. Put producer plugins (for example RPC) before consumers (for example API docs) when one plugin depends on another’s app-context output.

Testing harness

Honest exports lightweight helpers for common test setups.

import { createControllerTestApplication, createServiceTestContainer, createTestApplication } from 'honestjs'

const app = await createTestApplication({
	controllers: [UsersController],
	services: [UsersService]
})

const response = await app.request('/users')

const controllerApp = await createControllerTestApplication({
	controller: UsersController
})

const services = createServiceTestContainer({
	preload: [UsersService],
	overrides: [{ provide: UsersService, useValue: mockUsersService }]
})

Running tests in this package

This repo uses Bun's test runner. From the package root:

• bun test — run all tests once
• bun test --watch — watch mode
• bun test <pattern> — limit to matching file or test names (for example bun test application.bootstrap)
• bun run test:coverage — same suite with coverage (summary in the terminal and coverage/lcov.info)

Co-locate tests as *.test.ts next to sources. Import reflect-metadata first in any file that loads decorated classes, same as in application code.

Integration-style cases use *.integration.test.ts where the whole Application stack is exercised (for example the request pipeline). Shared HTTP fixtures for application tests live under src/testing/fixtures/ as factory functions so each test gets fresh decorator metadata after MetadataRegistry.clear() in afterEach.

Startup diagnostics guide mode

Enable startup guidance to get actionable remediation hints when initialization fails.

await Application.create(AppModule, {
	startupGuide: true
})

await Application.create(AppModule, {
	startupGuide: { verbose: true }
})

Guide mode emits startup diagnostics hints for common issues such as missing decorators, strict no-routes startup, and metadata issues.

License

MIT © Orkhan Karimov