DEV Community

Cover image for The Complete Guide to @hazeljs/cli: How to Use It, How It Works, and Why It Matters
Muhammad Arslan
Muhammad Arslan

Posted on • Edited on

The Complete Guide to @hazeljs/cli: How to Use It, How It Works, and Why It Matters

#cli #node #tooling #typescript

A deep dive into the HazelJS CLI — the scaffolding powerhouse that accelerates development from day one.

If you like it don't forget to Star HazelJS repository

Introduction

The @hazeljs/cli is the command-line interface for HazelJS — a TypeScript-first Node.js framework. It eliminates boilerplate, enforces best practices, and lets you focus on building features instead of wiring up infrastructure. Whether you're creating a new app, adding a REST endpoint, or scaffolding an AI agent, the CLI has you covered.

This guide covers everything: installation, usage patterns, architecture, benefits, and real-world workflows.

Table of Contents

  1. Installation
  2. Core Concepts
  3. Creating New Applications
  4. Generating Components
  5. Adding Packages
  6. Utility Commands
  7. How It Works Under the Hood
  8. Benefits and Why It Matters
  9. Real-World Workflows
  10. Best Practices

Installation

Global Installation (Recommended) 

npm install -g @hazeljs/cli
Enter fullscreen mode Exit fullscreen mode

This gives you the hazel command anywhere on your system. Verify with:

hazel --version
Enter fullscreen mode Exit fullscreen mode

Local Installation

For project-specific usage (e.g., in CI or scripts):

npm install --save-dev @hazeljs/cli
Enter fullscreen mode Exit fullscreen mode

Then run via npx:

npx hazel new my-app
Enter fullscreen mode Exit fullscreen mode

No Installation: npx

You can skip installation entirely:

npx @hazeljs/cli new my-app
Enter fullscreen mode Exit fullscreen mode

Core Concepts

The CLI is built around three pillars:

  1. Project scaffolding — Create new HazelJS applications with hazel new
  2. Code generation — Generate controllers, services, modules, and more with hazel generate (alias: hazel g)
  3. Package management — Add HazelJS packages with hazel add

Every generator supports:

  • -p, --path <path> — Custom output directory
  • --dry-run — Preview what would be created without writing files

Creating New Applications

Basic Usage 

hazel new my-app
Enter fullscreen mode Exit fullscreen mode

This scaffolds a complete project:

File / Folder Purpose
src/index.ts Entry point with CORS and HazelApp bootstrap
src/app.module.ts Root module with @HazelModule
src/hello.controller.ts Example controller
package.json Dependencies, scripts, ESLint devDependencies
tsconfig.json TypeScript with decorators, strict mode
.eslintrc.js ESLint + TypeScript + Prettier
.gitignore Sensible defaults

Interactive Mode

For full control over initial setup:

hazel new my-app --interactive
# or
hazel new my-app -i
Enter fullscreen mode Exit fullscreen mode

Interactive mode walks you through:

  1. Description — Project description for package.json
  2. Author — Your name
  3. License — Apache-2.0, MIT, GPL-3.0, BSD-3-Clause, or ISC
  4. Packages — Select from 23 HazelJS packages to install and scaffold

When you select packages, the CLI:

  • Installs the npm packages
  • Updates app.module.ts with correct imports and module registration
  • Creates .env and .env.example when Config is selected
  • Sets up Swagger in index.ts when Swagger is selected

Available Packages in Interactive Mode

Package What Gets Scaffolded
@hazeljs/ai AIModule in app module
@hazeljs/agent AgentModule in app module
@hazeljs/auth JwtModule.forRoot()
@hazeljs/cache CacheModule
@hazeljs/config ConfigModule.forRoot() + .env files
@hazeljs/cron CronModule
@hazeljs/data DataModule.forRoot()
@hazeljs/discovery Installed — use ServiceRegistry/DiscoveryClient
@hazeljs/event-emitter EventEmitterModule.forRoot()
@hazeljs/gateway GatewayModule
@hazeljs/graphql GraphQLModule
@hazeljs/grpc GrpcModule
@hazeljs/kafka KafkaModule
@hazeljs/messaging MessagingModule
@hazeljs/ml MLModule.forRoot()
@hazeljs/pdf-to-audio PdfToAudioModule
@hazeljs/prisma PrismaModule
@hazeljs/queue QueueModule
@hazeljs/rag RAGModule
@hazeljs/resilience Installed — use CircuitBreaker, WithRetry
@hazeljs/serverless Installed — use createLambdaHandler
@hazeljs/swagger SwaggerModule + index.ts setup
@hazeljs/websocket WebSocketModule

Options

Flag Description
-d, --dest <path> Destination directory (default: .)
--skip-install Skip npm install
--skip-git Skip git init
-i, --interactive Interactive project setup

Generating Components

All generators live under hazel generate (alias: hazel g).

Quick Reference

Command Alias Creates
hazel g controller <name> c name.controller.ts
hazel g service <name> s name.service.ts
hazel g module <name> m Module + controller + service + DTOs
hazel g dto <name> d name.dto.ts + update-name.dto.ts
hazel g guard <name> gu name.guard.ts
hazel g interceptor <name> i name.interceptor.ts
hazel g middleware <name> mw name.middleware.ts
hazel g filter <name> f name.filter.ts
hazel g pipe <name> — name.pipe.ts
hazel g crud <name> — Full CRUD resource
hazel g auth — Auth module + JWT guard + DTOs
hazel g gateway <name> ws name.gateway.ts
hazel g repository <name> repo name.repository.ts
hazel g ai-service <name> ai name.ai-service.ts
hazel g agent <name> — name.agent.ts
hazel g serverless <name> sls name.handler.ts
hazel g config — app.config.ts
hazel g cache <name> — name.cache.ts
hazel g cron <name> job name.cron.ts
hazel g rag <name> — name.rag.ts
hazel g discovery <name> — name.discovery.ts

High-Value Generators

CRUD — Full REST resource in one command:

hazel g crud product
Enter fullscreen mode Exit fullscreen mode

Creates controller, service, DTOs, and module.

Auth — Complete authentication module:

hazel g auth
Enter fullscreen mode Exit fullscreen mode

Creates auth module, service, controller, JWT guard, and DTOs.

Module — Feature module with 5 files:

hazel g module users
Enter fullscreen mode Exit fullscreen mode

Creates users.module.ts, controller, service, and DTOs.

The --dry-run Flag

Preview without writing:

hazel g module users --dry-run
Enter fullscreen mode Exit fullscreen mode

Output:

[dry-run] Would create /path/to/src/users/users.module.ts
[dry-run] Would create /path/to/src/users/users.controller.ts
...
Enter fullscreen mode Exit fullscreen mode

Adding Packages

The hazel add command installs HazelJS packages and shows usage hints:

hazel add auth
Enter fullscreen mode Exit fullscreen mode

Runs npm install @hazeljs/auth and prints:

Usage:
  import { JwtModule } from "@hazeljs/auth";
  // JwtModule.forRoot({ secret: "your-secret", expiresIn: "1d" })
Enter fullscreen mode Exit fullscreen mode

Interactive Mode 

hazel add
Enter fullscreen mode Exit fullscreen mode

Without a package name, shows an interactive list of all 23 available packages.

Available Packages

Short name npm package
ai @hazeljs/ai
agent @hazeljs/agent
auth @hazeljs/auth
cache @hazeljs/cache
config @hazeljs/config
cron @hazeljs/cron
data @hazeljs/data
discovery @hazeljs/discovery
event-emitter @hazeljs/event-emitter
gateway @hazeljs/gateway
graphql @hazeljs/graphql
grpc @hazeljs/grpc
kafka @hazeljs/kafka
messaging @hazeljs/messaging
ml @hazeljs/ml
pdf-to-audio @hazeljs/pdf-to-audio
prisma @hazeljs/prisma
queue @hazeljs/queue
rag @hazeljs/rag
resilience @hazeljs/resilience
serverless @hazeljs/serverless
swagger @hazeljs/swagger
websocket @hazeljs/websocket

Utility Commands

Info

Display project information:

hazel info
Enter fullscreen mode Exit fullscreen mode

Shows name, version, HazelJS packages, structure, environment, and config files.

Build

Build the project:

hazel build
hazel build --watch   # watch mode
Enter fullscreen mode Exit fullscreen mode

Start

Start the application:

hazel start
hazel start --dev     # development mode with hot-reload
Enter fullscreen mode Exit fullscreen mode

Test

Run tests:

hazel test
hazel test --watch    # watch mode
hazel test users      # run specific test pattern
Enter fullscreen mode Exit fullscreen mode

PDF to Audio

Convert PDFs to audio via a running app with @hazeljs/pdf-to-audio:

hazel pdf-to-audio convert document.pdf -o output.mp3 --api-url http://localhost:3000
hazel pdf-to-audio status <jobId> --api-url http://localhost:3000
Enter fullscreen mode Exit fullscreen mode

How It Works Under the Hood

Template-Based Generation

The CLI uses Mustache for templating. Every generator:

  1. Accepts a name (e.g., users)
  2. Resolves template data (PascalCase, kebab-case, etc.)
  3. Renders the template
  4. Writes the file 
hazel g controller users  →  Generator  →  Mustache  →  users.controller.ts
Enter fullscreen mode Exit fullscreen mode

Unified Generator Class

All generators extend a base class with a suffix property:

  • Controller → name.controller.ts
  • Service → name.service.ts
  • Guard → name.guard.ts

This keeps naming consistent across the codebase.

Shared Utilities

  • toPascalCase — users → Users
  • toKebabCase — UsersService → users-service
  • toCamelCase — UsersService → usersService
  • renderTemplate — Mustache rendering

Template Location

The hazel new command copies from @template inside the CLI package. This includes:

  • package.json with ESLint, TypeScript, Jest
  • tsconfig.json with strict mode
  • src/index.ts, src/app.module.ts, src/hello.controller.ts
  • .eslintrc.js, .gitignore, .env.example

Benefits and Why It Matters

1. Speed

  • New project in seconds — hazel new my-app -i gives you a configured app with chosen packages
  • CRUD in one command — hazel g crud product instead of 4+ manual files
  • Consistent structure — No guessing where files go

2. Best Practices Built-In

  • TypeScript with decorators and strict mode
  • ESLint + Prettier from the start
  • Jest for testing
  • Proper module/controller/service separation

3. Reduced Boilerplate

  • Controllers with full CRUD
  • DTOs with class-validator
  • Guards, interceptors, pipes with correct interfaces
  • Auth module with JWT + DTOs

4. Package Integration

  • hazel add installs and shows usage hints
  • Interactive mode wires modules into app.module.ts
  • Generators produce code that works with each package

5. Discoverability

  • hazel add (no args) shows all packages
  • hazel new -i shows all packages for scaffolding
  • --dry-run lets you explore before committing

6. Flexibility

  • -p for custom paths
  • --skip-install for CI
  • --skip-git when git is already initialized

Real-World Workflows

Building a REST API 

# 1. Create the project
hazel new my-api -i
# Select: config, swagger, prisma, auth

# 2. Generate features
hazel g crud users
hazel g crud products

# 3. Add caching
hazel add cache
hazel g cache product

# 4. Add cron for cleanup
hazel add cron
hazel g cron cleanup
Enter fullscreen mode Exit fullscreen mode

Building an AI Application 

# 1. Create the project
hazel new ai-app -i
# Select: config, ai, agent, rag

# 2. Generate AI service
hazel g ai-service chat

# 3. Generate RAG pipeline
hazel g rag knowledge

# 4. Create an AI agent
hazel g agent research
Enter fullscreen mode Exit fullscreen mode

Building a Real-Time App 

# 1. Create the project
hazel new realtime-app -i
# Select: config, auth, websocket

# 2. Generate auth
hazel g auth

# 3. Generate WebSocket gateways
hazel g gateway chat
hazel g gateway notifications
Enter fullscreen mode Exit fullscreen mode

Going Serverless 

# 1. Create the project
hazel new serverless-api

# 2. Add serverless
hazel add serverless

# 3. Generate handler
hazel g serverless api --platform lambda
# or: hazel g serverless api --platform cloud-function
Enter fullscreen mode Exit fullscreen mode

Best Practices

  1. Use modules to organize features — hazel g module <feature> gives you the full structure.

  2. Always use --dry-run first — Preview before writing to disk.

  3. Leverage aliases — hazel g c, hazel g s, hazel g m for speed.

  4. Use -p for organization — Place controllers in feature dirs: hazel g c users -p src/users.

  5. Start with CRUD — For standard REST resources, hazel g crud <name> gives everything in one shot.

  6. Use interactive mode for new projects — hazel new my-app -i sets up everything correctly from the start.

  7. Add packages as you need them — hazel add keeps dependencies and hints in sync.

Summary

The @hazeljs/cli is your accelerator for HazelJS development. It:

  • Scaffolds new apps with 23 package options
  • Generates 21+ component types with one command
  • Adds packages with usage hints
  • Runs build, start, test, and PDF-to-audio utilities

Built on Mustache templates and a unified generator pattern, it enforces consistency and best practices while keeping you in control. Use --dry-run to explore, -i for interactive setup, and -p for custom paths.

Get started: npm install -g @hazeljs/cli and run hazel new my-app -i.

For more details, see the CLI package documentation.

Top comments (0)