Introduction to HazelJS
A modern, lightweight, enterprise-grade Node.js framework built with TypeScript. Build scalable server-side applications using decorators, dependency injection, and a modular architecture.
🎯What is HazelJS?
HazelJS is a progressive Node.js framework designed for building efficient, reliable, and scalable server-side applications. It combines the best practices from modern frameworks with a focus on developer experience, type safety, and performance.
Core Philosophy
- ✨Developer Experience First: Intuitive decorator-based API that's easy to learn and use
- ⚡Performance: Lightweight design with minimal overhead and fast startup times
- 🔒Type Safety: Built with TypeScript from the ground up for compile-time safety
- 🧩Modularity: Pick and choose only the packages you need for your project
- 🏗️Enterprise Ready: Built-in features for production applications
🏗️Architecture
HazelJS follows a modular, decorator-based architecture that promotes separation of concerns and code reusability. The framework is built on top of a powerful dependency injection system and uses metadata reflection for configuration.
Application Architecture
📦Modular Design
HazelJS is organized as a monorepo with independent packages. Each package can be installed separately, allowing you to use only what you need.
- •
@hazeljs/core- Core framework - •
@hazeljs/ai- AI integration - •
@hazeljs/auth- Authentication - •
@hazeljs/cache- Caching - • And 6 more packages...
💉Dependency Injection
Built-in DI container with support for multiple scopes and automatic dependency resolution. No manual wiring required.
- • Singleton scope (default)
- • Transient scope (new instance per injection)
- • Request scope (per HTTP request)
- • Circular dependency detection
- • Property-based injection
Module System
Modules encapsulate related functionality. They can import other modules, export providers, and declare controllers. The DI container automatically resolves dependencies across modules.
⚙️Technical Details
Decorator-Based Configuration
HazelJS uses TypeScript decorators and metadata reflection to configure your application. This approach provides a clean, declarative API that's both type-safe and easy to understand.
@Controller('users')
export class UsersController {
constructor(private usersService: UsersService) {}
@Get()
findAll() {
return this.usersService.findAll();
}
}Decorators store metadata that the framework uses to set up routing, dependency injection, and middleware automatically.
Request Lifecycle
Every HTTP request goes through a well-defined pipeline:
- Routing: Framework matches the request to a controller method
- Middleware: Global and route-specific middleware execute
- Guards: Authentication and authorization checks
- Interceptors: Request transformation before handler
- Pipes: Parameter validation and transformation
- Handler: Controller method executes business logic
- Interceptors: Response transformation after handler
- Exception Filters: Error handling if exceptions occur
- Response: Final response sent to client
Dependency Injection Container
The DI container is the heart of HazelJS. It manages the lifecycle of all providers and automatically resolves dependencies using reflection metadata.
@Injectable()
export class UsersService {
constructor(
private prisma: PrismaService,
private cache: CacheService
) {}
// Dependencies automatically injected
}The container uses TypeScript's reflection metadata to determine parameter types and automatically provides the correct instances.
💡Why HazelJS?
HazelJS combines the best features of modern Node.js frameworks with a focus on simplicity, performance, and developer experience.
vs NestJS
- ✓Lighter weight with smaller bundle size
- ✓Built-in AI service integration
- ✓Simpler learning curve
- ✓Native Prisma integration
- ✓No Express/Fastify dependency
vs Express
- ✓Decorator-based API
- ✓Built-in dependency injection
- ✓Automatic request validation
- ✓Full TypeScript type safety
- ✓Modular architecture
- ✓Built-in testing utilities
✨Key Features
🎯Decorator-Based API
Clean, intuitive programming model with @Controller,@Injectable,@Get,@Post decorators. Declarative configuration that's easy to read and maintain.
💉Advanced Dependency Injection
Singleton, Transient, and Request-scoped providers with circular dependency detection. Automatic dependency resolution using TypeScript reflection metadata.
🤖Built-in AI Service
Native integration with OpenAI, Anthropic, Gemini, Cohere, and Ollama. Use decorators like @AITask to add AI capabilities to your methods.
🗄️Prisma Integration
First-class ORM support with repository pattern and automatic migrations. Type-safe database access with full TypeScript support.
🛡️Exception Filters & Testing
Centralized error handling with exception filters. Full test module builder with mocking support for easy unit and integration testing.
🛣️Advanced Routing
Wildcards, optional params, API versioning with multiple strategies (URI, Header, Media Type). Flexible routing that adapts to your needs.
🚀Getting Started
Ready to start building with HazelJS? Follow these steps to get up and running in minutes.
💻Quick Example
Here's a simple example to show how easy it is to build with HazelJS:
import { HazelApp, HazelModule, Controller, Get, Injectable } from '@hazeljs/core';
@Injectable()
export class AppService {
getHello() {
return 'Hello from HazelJS!';
}
}
@Controller('hello')
export class HelloController {
constructor(private appService: AppService) {}
@Get()
hello() {
return { message: this.appService.getHello() };
}
}
@HazelModule({
controllers: [HelloController],
providers: [AppService],
})
export class AppModule {}
async function bootstrap() {
const app = new HazelApp(AppModule);
await app.listen(3000);
console.log('🚀 Application running on http://localhost:3000');
}
bootstrap();This example demonstrates dependency injection, routing, and module organization. Visit http://localhost:3000/hello to see it in action.
🤝Community
Join our growing community of developers building with HazelJS. We welcome contributions of all kinds, from bug reports to feature requests and pull requests.