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

Use this table when you know the goal but not the package name. Each row includes @hazeljs/core where it is required. Full list: Available Packages below.

I want to...	Install
Build a basic HTTP API	@hazeljs/core
Scaffold projects from the CLI	@hazeljs/core @hazeljs/cli
Add LLM integration (OpenAI, Anthropic, etc.)	@hazeljs/core @hazeljs/ai
Build AI agents with tools	@hazeljs/core @hazeljs/ai @hazeljs/agent
Add RAG / semantic search over documents	@hazeljs/core @hazeljs/ai @hazeljs/rag
Build agents and RAG with shared conversation memory	@hazeljs/core @hazeljs/ai @hazeljs/agent @hazeljs/rag (+ optional @hazeljs/memory)
Versioned prompt templates (not inline strings)	@hazeljs/core @hazeljs/prompts (+ @hazeljs/ai when calling LLMs)
Persistent memory store (Redis/Prisma) for agents or RAG	@hazeljs/core @hazeljs/memory
Block PII / prompt injection / unsafe LLM output	@hazeljs/core @hazeljs/guardrails (+ @hazeljs/ai)
Regression-test RAG or agents (golden datasets, CI)	@hazeljs/core @hazeljs/eval (+ @hazeljs/rag or @hazeljs/agent)
Trace LLM calls and agent steps (OpenTelemetry)	@hazeljs/core @hazeljs/observability (+ @hazeljs/ai / @hazeljs/agent)
Connect to MCP tool servers	@hazeljs/core @hazeljs/mcp (+ @hazeljs/ai / @hazeljs/agent)
ML models, feature store, batch inference	@hazeljs/core @hazeljs/ml
Add authentication (JWT)	@hazeljs/core @hazeljs/auth
Add OAuth social login	@hazeljs/core @hazeljs/auth @hazeljs/oauth
Fine-grained authorization (roles/abilities)	@hazeljs/core @hazeljs/casl (+ @hazeljs/auth)
Audit log who did what	@hazeljs/core @hazeljs/audit
Add database (Prisma)	@hazeljs/core @hazeljs/prisma
Add database (TypeORM)	@hazeljs/core @hazeljs/typeorm
Add caching (Redis/memory)	@hazeljs/core @hazeljs/cache
Type-safe config / .env	@hazeljs/core @hazeljs/config
Background jobs with Redis (BullMQ)	@hazeljs/core @hazeljs/queue
CPU-intensive work off the main thread	@hazeljs/core @hazeljs/worker
Scheduled recurring tasks (cron expressions)	@hazeljs/core @hazeljs/cron
Durable workflows (wait/resume, idempotency)	@hazeljs/core @hazeljs/flow
Run flows as a standalone HTTP service	@hazeljs/core @hazeljs/flow-runtime
Event streaming between microservices (Kafka)	@hazeljs/core @hazeljs/kafka
Google Cloud Pub/Sub messaging	@hazeljs/core @hazeljs/pubsub
WhatsApp / Telegram / Viber bots	@hazeljs/core @hazeljs/messaging (+ @hazeljs/ai)
In-process pub/sub between modules	@hazeljs/core @hazeljs/event-emitter
Distributed saga / compensation across services	@hazeljs/core @hazeljs/saga
Distributed lock (only one instance runs a job)	@hazeljs/core @hazeljs/distributed-lock
Service discovery for microservices	@hazeljs/core @hazeljs/discovery
API gateway (versioning, canary routing)	@hazeljs/core @hazeljs/gateway
Circuit breaker, retry, rate limit	@hazeljs/core @hazeljs/resilience
Real-time WebSocket / SSE	@hazeljs/core @hazeljs/websocket
Realtime subscriptions (higher-level than raw WS)	@hazeljs/core @hazeljs/realtime
GraphQL API	@hazeljs/core @hazeljs/graphql
gRPC services	@hazeljs/core @hazeljs/grpc
OpenAPI / Swagger docs	@hazeljs/core @hazeljs/swagger
ETL / data pipelines	@hazeljs/core @hazeljs/data
Feature flags	@hazeljs/core @hazeljs/feature-toggle
i18n / translations	@hazeljs/core @hazeljs/i18n
Inspect routes, cron, agents at runtime	@hazeljs/core @hazeljs/inspector
Deploy serverless (AWS Lambda)	@hazeljs/core @hazeljs/serverless
Ops/incident triage (Jira, Slack)	@hazeljs/core @hazeljs/ops-agent (+ @hazeljs/agent @hazeljs/ai)
PDF documents to audio (TTS)	@hazeljs/core @hazeljs/pdf-to-audio (+ @hazeljs/ai)
End-to-end support chat + RAG example	See Support Agent (uses core, rag, ai, memory patterns)

Similar packages — quick picks: Queue vs Worker vs Cron · Flow vs Flow Runtime · Kafka vs Pub/Sub vs Messaging · RAG vs Agentic RAG · Memory in RAG vs @hazeljs/memory

Available Packages

Install any package with npm:

npm install @hazeljs/core @hazeljs/ai

Browse full documentation from the docs sidebar or each package page linked in the table above.

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