create-hono-decorator

🚀 CLI tool to scaffold a production-ready Hono backend with TypeScript decorators.

✨ Features

The generated template includes:

• 🎨 TypeScript Decorators - NestJS-inspired decorators for clean, declarative code
• 🔐 Authentication & Authorization - JWT auth with role-based and permission-based access control
• ⚡ Redis Caching - Built-in Redis caching with TTL support
• 🚦 Rate Limiting - Route-specific and global rate limiting
• 📊 Observability - Structured logging (Pino), Prometheus metrics, request tracing
• 🗄️ Database - Drizzle ORM with PostgreSQL/MySQL/SQLite support
• ✅ Validation - Zod schemas with type-safe validation
• 🧪 Testing Ready - Vitest setup included
• 📝 Documentation - Comprehensive docs and examples
• 🐳 Docker Ready - Production-ready Dockerfile and docker-compose

📦 Usage

# Using bunx (recommended)
bunx create-hono-decorator my-app

# Using npm
npm create hono-decorator my-app

# Using yarn
yarn create hono-decorator my-app

# Using pnpm
pnpm create hono-decorator my-app

🚀 Quick Start

After creating your project:

cd my-app

# 1. Install dependencies (if not auto-installed)
bun install

# 2. Configure environment
# Edit .env with your database credentials
nano .env

# 3. Run database migrations
bun run db:migrate

# 4. Start development server
bun run dev

Your API will be available at http://localhost:3000

📖 What You Get

Project Structure

my-app/
├── src/
│   ├── config/           # Configuration (env, cache, logger, security)
│   ├── core/             # Core framework (DI container, route builder)
│   ├── decorators/       # Decorators (route, guard, validation)
│   ├── middleware/       # Middleware (auth, logger, rate limit)
│   ├── platforms/        # Platform-specific routes (web, mobile)
│   │   └── web/
│   │       └── controllers/
│   ├── services/         # Business logic services
│   ├── db/              # Database schema and migrations
│   └── server.ts        # Application entry point
├── docs/                # Comprehensive documentation
├── tests/              # Test files
└── logs/               # Application logs

Example Code

Simple Controller:

import { Controller, Get, Post, Injectable } from '@/decorators';
import { UserService } from '@/services/user.service';

@Controller('/users', { platform: 'web', version: 'v1' })
@Injectable()
export class UserController {
  constructor(private userService: UserService) {}

  @Get()
  @Public()
  @Cache({ ttl: 60 })
  async getAll() {
    return await this.userService.getAll();
  }

  @Post()
  @RequireAuth()
  @RateLimit({ max: 10, windowMs: 60000 })
  async create(@ValidatedBody(CreateUserSchema) dto: CreateUserDto) {
    return await this.userService.create(dto);
  }
}

Authentication:

@Get('/profile')
@RequireAuth()
async getProfile(@User() user: UserDto) {
  return user;
}

@Delete('/admin/users/:id')
@RequireAuth()
@RequireRole('admin')
async deleteUser(@Param('id') id: string) {
  return await this.userService.delete(id);
}

📚 Documentation

The template includes comprehensive documentation:

• README.md - Quick start and overview
• docs/GETTING_STARTED.md - Step-by-step tutorial
• docs/DECORATORS.md - Complete decorator reference
• docs/ARCHITECTURE.md - System architecture
• docs/API_REFERENCE.md - API documentation

🛠️ Available Scripts

bun run dev          # Start development server with hot reload
bun run build        # Build for production
bun run start        # Start production server

bun run db:generate  # Generate database migrations
bun run db:migrate   # Run pending migrations
bun run db:studio    # Open Drizzle Studio (database GUI)

bun test            # Run tests
bun test:watch      # Run tests in watch mode
bun test:coverage   # Generate coverage report

bun run lint        # Run ESLint
bun run format      # Format code with Prettier

🌍 Environment Setup

The template includes a .env.example file. Copy it to .env and configure:

# Server
NODE_ENV=development
PORT=3000

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/dbname

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379

# JWT
JWT_SECRET=your-super-secret-key
JWT_EXPIRES_IN=7d

# Rate Limiting
RATE_LIMIT_MAX=100

🎯 Key Features Explained

Decorators

Use familiar NestJS-style decorators:

• Route: @Get(), @Post(), @Put(), @Delete()
• Parameters: @Body(), @Query(), @Param(), @User()
• Validation: @ValidatedBody(), @ValidatedQuery()
• Guards: @RequireAuth(), @RequireRole(), @RequirePermission()
• Utilities: @RateLimit(), @Cache(), @LogActivity()

Dependency Injection

Automatic dependency injection with decorators:

@Injectable()
@Singleton()
class Database {}

@Injectable()
class UserService {
  constructor(private db: Database) {} // Auto-injected
}

Rate Limiting

Flexible rate limiting per route or globally:

@Post('/login')
@RateLimit({ max: 5, windowMs: 900000 }) // 5 attempts per 15 min
async login(@Body() credentials: LoginDto) { }

Caching

Simple Redis caching with TTL:

@Get()
@Cache({ ttl: 300 }) // Cache for 5 minutes
async getAll() { }

🤝 Contributing

Found a bug or have a suggestion? Please open an issue on GitHub.

📄 License

MIT © Mad1Duck

🔗 Links

• Template Repository
• Hono Documentation
• TypeScript Decorators
• Drizzle ORM