Installation

Get started with HazelJS in minutes. Choose the installation method that works best for your setup.

Prerequisites

Before installing HazelJS, ensure you have the following installed on your system:

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

Note: If you don't have Node.js installed, visit nodejs.org to download and install it. We recommend using Node.js 20 LTS for the best experience.

Installation Methods

Using npm (Recommended)

The easiest and most common way to install HazelJS. Works on Windows, macOS, and Linux.

Install the CLI globally:

npm install -g @hazeljs/cli

This installs the HazelJS command-line interface globally, making it available from any directory.

Or install in your project:

npm install @hazeljs/core

Install HazelJS as a project dependency for a specific application.

Install specific packages:

npm install @hazeljs/core @hazeljs/ai @hazeljs/auth
npm install @hazeljs/cache @hazeljs/prisma

Install only the packages you need for your project.

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/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/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/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 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 Installation

After installation, verify that HazelJS is installed correctly:

# Check CLI version
hazeljs --version
# Should display: v0.2.0

# Check available commands
hazeljs --help

Creating Your First Project

Once HazelJS is installed, create a new project:

# Create a new HazelJS application
hazeljs new my-app

# Navigate to your project
cd my-app

# Start the development server
npm run dev

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

Manual Project Setup

If you prefer to set up manually without the 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!"}.

Environment Variables

Create a .env file in your project root:

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

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

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.

What's Next?

• Controllers Guide — Build RESTful APIs with decorator-based controllers
• Providers Guide — Understand dependency injection and services
• Modules Guide — Organize your application with modules
• Packages — Explore all available HazelJS packages