Introduction to HazelJS

An AI-native backend framework built with TypeScript. Production-grade Agent Runtime, Agentic RAG, and persistent memory — designed for stateful AI agents and LLM-powered applications. Build with decorators, dependency injection, and a modular architecture.

🎯What is HazelJS?

HazelJS is an AI-native Node.js framework designed for building intelligent, stateful backend applications. It combines production-grade Agent Runtime, Agentic RAG, and built-in AI integration with enterprise features: dependency injection, type safety, and a modular architecture. AI is at the core of every design decision—not bolted on.

🏗️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.

graph TD
    A["HTTP Request"] --> B["Routing Layer<br/>(@Controller, @Get, @Post)"]
    B --> C["Middleware Pipeline<br/>(Global & Route-specific)"]
    C --> D["Guards<br/>(Authentication & Authorization)"]
    D --> E["Interceptors<br/>(Request/Response Transformation)"]
    E --> F["Pipes<br/>(Validation & Transformation)"]
    F --> G["Controller Handler<br/>(Business Logic)"]
    G --> H["Services<br/>(Dependency Injection)"]
    H --> I["Data Layer<br/>(Prisma, Cache, External APIs)"]
    I --> J["Response"]
    
    style A fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style B fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style C fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff
    style D fill:#f59e0b,stroke:#fbbf24,stroke-width:2px,color:#fff
    style E fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style F fill:#ec4899,stroke:#f472b6,stroke-width:2px,color:#fff
    style G fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style H fill:#06b6d4,stroke:#22d3ee,stroke-width:2px,color:#fff
    style I fill:#14b8a6,stroke:#2dd4bf,stroke-width:2px,color:#fff
    style J fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff

graph LR
    A["AppModule<br/>(Root Module)"] --> B["Feature Modules"]
    B --> C["UsersModule"]
    B --> D["ProductsModule"]
    B --> E["AuthModule"]
    
    C --> F["Controllers<br/>Services<br/>Providers"]
    D --> F
    E --> F
    
    F --> G["DI Container<br/>(Automatic Resolution)"]
    
    style A fill:#3b82f6,stroke:#60a5fa,stroke-width:2px,color:#fff
    style B fill:#10b981,stroke:#34d399,stroke-width:2px,color:#fff
    style C fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style D fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style E fill:#8b5cf6,stroke:#a78bfa,stroke-width:2px,color:#fff
    style F fill:#f59e0b,stroke:#fbbf24,stroke-width:2px,color:#fff
    style G fill:#06b6d4,stroke:#22d3ee,stroke-width:2px,color:#fff

⚙️Technical Details

@Controller('users')
export class UsersController {
  constructor(private usersService: UsersService) {}
  
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Injectable()
export class UsersService {
  constructor(
    private prisma: PrismaService,
    private cache: CacheService
  ) {}
  
  // Dependencies automatically injected
}

💡Why HazelJS?

HazelJS combines the best features of modern Node.js frameworks with a focus on simplicity, performance, and developer experience.

✨Key Features

🚀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.