HazelJS Installation

Install HazelJS and create a new HazelJS application. This page covers prerequisites, installation methods, project setup, available packages, and troubleshooting.

Quick Reference

• Purpose: Install HazelJS framework and create a new HazelJS project.
• When to use: Reference this page when installing HazelJS for the first time, adding HazelJS packages to an existing project, or troubleshooting installation issues.
• Key concepts: @hazeljs/core (required), @hazeljs/cli (scaffolding), optional packages (@hazeljs/ai, @hazeljs/agent, @hazeljs/rag, etc.), tsconfig.json requirements (experimentalDecorators: true, emitDecoratorMetadata: true).
• Inputs: Node.js 18+, npm 9+.
• Outputs: A running HazelJS application on http://localhost:3000.
• Dependencies: Node.js 18+, TypeScript, class-validator, class-transformer.
• Common patterns: Install CLI globally → hazel new my-app -i → npm run dev; or manual setup with npm install @hazeljs/core → create tsconfig.json → create src/main.ts → npm run dev.
• Common mistakes: Missing experimentalDecorators: true in tsconfig.json; missing emitDecoratorMetadata: true in tsconfig.json; using Node.js < 18; forgetting to install class-validator and class-transformer for DTO validation.

HazelJS Prerequisites

• Node.js — Version 18.x or later (node --version). Recommended: Node.js 20 LTS.
• npm — Version 9.x or later (npm --version)
• Git — Optional, for development (git --version)

HazelJS Installation Methods

Install HazelJS via npm (Recommended)

# Install the HazelJS CLI globally
npm install -g @hazeljs/cli

# Create a new HazelJS app (quick skeleton)
hazel g app my-app
cd my-app
npm install
npm run dev

Or create a new HazelJS app with interactive prompts:

hazel new my-app -i

Install HazelJS Core in an Existing Project

npm install @hazeljs/core

Install Specific HazelJS Packages

# Example: install core + AI + auth
npm install @hazeljs/core @hazeljs/ai @hazeljs/auth

# Example: install core + caching + database
npm install @hazeljs/core @hazeljs/cache @hazeljs/prisma

HazelJS Package Decision Guide

I want to...	Install
Build a basic HTTP API	@hazeljs/core
Add LLM integration (OpenAI, Anthropic, etc.)	@hazeljs/core @hazeljs/ai
Build AI agents with tools and memory	@hazeljs/core @hazeljs/ai @hazeljs/agent @hazeljs/rag
Add RAG / semantic search	@hazeljs/core @hazeljs/ai @hazeljs/rag
Add authentication (JWT)	@hazeljs/core @hazeljs/auth
Add OAuth social login	@hazeljs/core @hazeljs/auth @hazeljs/oauth
Add database (Prisma)	@hazeljs/core @hazeljs/prisma
Add caching (Redis/memory)	@hazeljs/core @hazeljs/cache
Add real-time (WebSocket/SSE)	@hazeljs/core @hazeljs/websocket
Add resilience (circuit breaker, retry)	@hazeljs/core @hazeljs/resilience
Regression-test RAG or agents (golden datasets, CI)	@hazeljs/core @hazeljs/eval
Deploy serverless (AWS Lambda)	@hazeljs/core @hazeljs/serverless

Available Packages

Package	npm downloads	Description
@hazeljs/core		Core framework (required) — Dependency injection, routing, decorators, base functionality
@hazeljs/cli		CLI for scaffolding and generating HazelJS applications and components
@hazeljs/ai		AI integration — OpenAI, Anthropic, Gemini, Cohere
@hazeljs/agent		AI-native Agent Runtime — stateful agents with tools, memory, and human-in-the-loop
@hazeljs/rag		Retrieval-Augmented Generation and vector search
@hazeljs/eval		Golden datasets, IR/RAG metrics, agent trajectory scoring, CI eval reporting
@hazeljs/ml		Machine Learning and model management
@hazeljs/auth		Authentication and JWT
@hazeljs/oauth		OAuth 2.0 social login — Google, Microsoft, GitHub, Facebook, Twitter
@hazeljs/cache		Caching — Memory, Redis, CDN
@hazeljs/config		Type-safe configuration management
@hazeljs/cron		Cron job scheduling with decorators
@hazeljs/flow		Durable execution graph engine — workflows with wait/resume, idempotency, optional Prisma
@hazeljs/flow-runtime		Standalone HTTP service for flow — start/tick/resume runs via REST API
@hazeljs/prisma		Prisma ORM integration
@hazeljs/swagger		Swagger/OpenAPI documentation
@hazeljs/websocket		WebSocket and Server-Sent Events
@hazeljs/graphql		GraphQL server and client with decorators
@hazeljs/grpc		gRPC server and client with decorators
@hazeljs/kafka		Kafka — produce, consume, and stream processing
@hazeljs/queue		Redis-backed job queue (BullMQ)
@hazeljs/worker		CPU-intensive task offloading via worker threads
@hazeljs/data		Data processing and ETL pipelines
@hazeljs/messaging		Multichannel messaging — WhatsApp, Telegram, Viber with LLM-powered bots
@hazeljs/discovery		Service discovery and registry for microservices
@hazeljs/event-emitter		Event-driven architecture with decorators
@hazeljs/resilience		Circuit breaker, retry, rate limit, bulkhead, timeout
@hazeljs/gateway		API gateway — version routing, canary deployments
@hazeljs/inspector		Framework-aware runtime inspector — discover routes, cron, agents, flows in one dashboard
@hazeljs/guardrails		Content safety — PII redaction, prompt injection detection, output validation
@hazeljs/serverless		Serverless adapters — AWS Lambda, Google Cloud Functions
@hazeljs/ops-agent		Ops agent for Jira, Slack, DevOps — AI-powered incident triage
@hazeljs/pdf-to-audio		Convert PDF documents to audio using TTS

Building HazelJS from Source

Build HazelJS from source if you want to contribute, customize, or use the latest development version.

# Step 1: Clone the repository
git clone https://github.com/hazel-js/hazeljs.git

# Step 2: Navigate to the project directory
cd hazeljs

# Step 3: Install dependencies
npm install

# Step 4: Build the project
npm run build

# Step 5: Link the CLI (optional)
npm link

Verifying HazelJS Installation

After installation, verify that HazelJS is installed correctly:

# Check CLI version
hazel --version
# Should display your installed CLI version

# Check available commands
hazel --help

Creating Your First HazelJS Project

Once HazelJS is installed, create a new project:

# Create a new HazelJS application
hazel new my-app -i

# Navigate to your project
cd my-app

# Start the development server
npm run dev

Your application will be available at http://localhost:3000.

Manual HazelJS Project Setup

If you prefer to set up manually without the HazelJS CLI:

1. Initialize a new project:

mkdir my-app && cd my-app
npm init -y
npm install @hazeljs/core class-validator class-transformer
npm install -D typescript @types/node ts-node-dev

2. Create tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "lib": ["ES2020"],
    "declaration": true,
    "outDir": "./dist",
    "rootDir": "./src",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "resolveJsonModule": true,
    "moduleResolution": "node"
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Important: experimentalDecorators and emitDecoratorMetadata must be true — HazelJS relies on TypeScript decorators and reflection metadata.

3. Create src/main.ts:

import { HazelApp, HazelModule, Controller, Get } from '@hazeljs/core';

@Controller('hello')
class HelloController {
  @Get()
  hello() {
    return { message: 'Hello, World!' };
  }
}

@HazelModule({
  controllers: [HelloController],
})
class AppModule {}

async function bootstrap() {
  const app = new HazelApp(AppModule);
  await app.listen(3000);
  console.log('Application is running on http://localhost:3000');
}

bootstrap();

4. Add scripts to package.json:

{
  "scripts": {
    "dev": "ts-node-dev --respawn src/main.ts",
    "build": "tsc",
    "start": "node dist/main.js"
  }
}

5. Run:

npm run dev

Visit http://localhost:3000/hello — you should see {"message":"Hello, World!"}.

HazelJS Environment Variables

Create a .env file in your HazelJS project root:

PORT=3000
NODE_ENV=development
DATABASE_URL=postgresql://user:password@localhost:5432/mydb
JWT_SECRET=your-secret-key

HazelJS Project Structure

A typical HazelJS project follows this structure:

my-app/
├── src/
│   ├── user/
│   │   ├── dto/
│   │   │   └── create-user.dto.ts
│   │   ├── user.controller.ts
│   │   ├── user.service.ts
│   │   └── user.module.ts
│   ├── app.module.ts
│   └── main.ts
├── .env
├── package.json
└── tsconfig.json

HazelJS Installation Troubleshooting

Permission Errors (npm install -g)

If you encounter permission errors when installing globally:

sudo npm install -g @hazeljs/cli

Or configure npm to use a different directory for global packages.

Command Not Found

If the hazeljs command is not found:

• Verify npm global bin directory is in your PATH
• Restart your terminal after installation
• Check installation with: npm list -g @hazeljs/cli

Version Conflicts

If you have multiple Node.js versions installed:

nvm use 20

Use nvm or n to manage Node.js versions.

Decorators Not Working

Ensure experimentalDecorators and emitDecoratorMetadata are both set to true in your tsconfig.json.

Validation Not Working

Install the required peer dependencies:

npm install class-validator class-transformer

Use @Body(DtoClass) decorator with your DTO class for automatic validation.

Related Pages

• Introduction — HazelJS overview and architecture
• Core Package — Core framework features and request pipeline
• Concepts & Glossary — All HazelJS decorators and terms

Next Concepts to Learn

• Controllers Guide — Build RESTful APIs with decorator-based controllers
• Providers Guide — Understand dependency injection and services
• Modules Guide — Organize your application with modules
• AI Package — Add LLM integration
• Agent Package — Build AI agents
• Eval Package — Regression-test RAG and agents with golden datasets