CLI Package

The @hazeljs/cli package provides a command-line interface for generating HazelJS components and scaffolding applications. It includes generators for controllers, services, modules, guards, interceptors, and more.

Purpose

Creating new components manually is repetitive and error-prone. You need to create files, write boilerplate code, set up tests, and ensure consistency across your project. The @hazeljs/cli package accelerates development by providing:

  • Component Generation: Generate controllers, services, modules, and more with a single command
  • Consistent Structure: Ensures all generated code follows HazelJS best practices
  • Test Files: Automatically generates test files alongside components
  • Scaffolding: Create new applications from templates
  • Time Saving: Reduces boilerplate writing and setup time significantly

Architecture

The CLI uses a template-based generation system:

Loading diagram...

Key Features

  1. Component Generators: Create controllers, services, modules, DTOs, guards, etc.
  2. Template System: Uses templates to ensure consistent code structure
  3. Path Configuration: Customize where files are generated
  4. Test Generation: Automatically creates test files

Advantages

1. Speed

Generate complete components with tests in seconds instead of minutes.

2. Consistency

All generated code follows the same patterns and best practices.

3. Best Practices

Templates include best practices like proper imports, decorators, and structure.

4. Reduced Errors

Less manual typing means fewer typos and mistakes.

5. Onboarding

New team members can quickly generate components without learning all the patterns.

6. Maintainability

Consistent code structure makes the codebase easier to maintain and understand.

Installation

npm install -g @hazeljs/cli

Quick Start

Create New Application

Generate a new HazelJS application:

hazel new my-app

This creates a new HazelJS application with the standard project structure.

Generate Components

Core Components

Controller

Generate a new controller:

hazel generate controller users
# or short form
hazel g controller users

This creates:

  • users.controller.ts - Controller file
  • users.controller.test.ts - Test file

Service

Generate a new service:

hazel g service users

Creates:

  • users.service.ts - Service file
  • users.service.test.ts - Test file

Module

Generate a new module:

hazel g module users

Creates:

  • users.module.ts - Module file
  • users.module.test.ts - Test file

DTO

Generate create and update DTOs:

hazel g dto product

Creates:

  • dto/create-product.dto.ts
  • dto/update-product.dto.ts

Advanced Components

Guard

Generate an authentication guard:

hazel g guard auth
# or
hazel g g auth

Interceptor

Generate an interceptor:

hazel g interceptor logging
# or
hazel g i logging

Exception Filter

Generate an exception filter:

hazel g filter http-exception
# or
hazel g f http-exception

Pipe

Generate a transformation pipe:

hazel g pipe validation
# or
hazel g p validation

Repository

Generate a Prisma repository:

hazel g repository user
# or
hazel g repo user

WebSocket Gateway

Generate a WebSocket gateway:

hazel g gateway notifications
# or
hazel g ws notifications

AI Service

Generate an AI service with decorators:

hazel g ai-service chat
# or
hazel g ai chat

Serverless Handler

Generate a serverless handler:

# AWS Lambda
hazel g serverless handler --platform lambda
# or
hazel g sls handler

# Google Cloud Function
hazel g serverless handler --platform cloud-function

Options

Path Option

Specify a custom path for generated files:

hazel g controller user -p src/modules/users

Platform Option

For serverless handlers, specify the platform:

hazel g serverless handler --platform lambda
hazel g serverless handler --platform cloud-function

Generated Files Examples

Controller

import { Controller, Get, Post, Body, Param } from '@hazeljs/core';

@Controller('users')
export class UsersController {
  @Get()
  findAll() {
    return 'This action returns all users';
  }

  @Get(':id')
  findOne(@Param('id') id: string) {
    return `This action returns user #${id}`;
  }

  @Post()
  create(@Body() createUserDto: any) {
    return 'This action creates a new user';
  }
}

Service

import { Injectable } from '@hazeljs/core';

@Injectable()
export class UsersService {
  findAll() {
    return [];
  }

  findOne(id: number) {
    return { id };
  }

  create(createUserDto: any) {
    return createUserDto;
  }
}

Module

import { HazelModule } from '@hazeljs/core';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@HazelModule({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}

Guard

import { Injectable } from '@hazeljs/core';
import { IAuthGuard, RequestContext, AuthGuardOptions } from '@hazeljs/auth';

@Injectable()
export class AuthGuard implements IAuthGuard {
  async canActivate(
    context: RequestContext,
    options?: AuthGuardOptions
  ): Promise<boolean> {
    // Your guard logic here
    return true;
  }
}

Repository

import { Injectable } from '@hazeljs/core';
import { PrismaService } from '@hazeljs/prisma';
import { BaseRepository } from '@hazeljs/prisma';

@Injectable()
export class UserRepository extends BaseRepository {
  constructor(prisma: PrismaService) {
    super(prisma, 'user');
  }

  // Add custom methods here
}

Workflow Example

Here's a typical workflow for creating a new feature:

# 1. Generate module
hazel g module products

# 2. Generate DTOs
hazel g dto product

# 3. Generate service
hazel g service products

# 4. Generate controller
hazel g controller products

# 5. Generate repository (if using Prisma)
hazel g repository product

Best Practices

  1. Use consistent naming: Follow the same naming convention across your project.

  2. Generate tests: Always generate test files and write tests for your components.

  3. Organize by feature: Group related components in feature modules.

  4. Customize templates: Modify generated files to match your project's patterns.

  5. Use path option: Organize files in a logical directory structure.

What's Next?