npm install -g @nestjs/cli

nest --version

nest new hello-nest

cd hello-nest
npm run start:dev

hello-nest/
├── src/                    # Source code directory
│   ├── app.controller.ts   # Controller (handles HTTP requests)
│   ├── app.module.ts       # Root module (organizes the app)
│   ├── app.service.ts      # Service (business logic)
│   └── main.ts             # Entry point (bootstraps the app)
├── test/                   # Test files
│   ├── app.e2e-spec.ts     # End-to-end tests
│   └── jest-e2e.json       # Jest configuration for E2E tests
├── .eslintrc.js            # ESLint configuration
├── .gitignore              # Git ignore rules
├── .prettierrc             # Prettier configuration
├── nest-cli.json            # NestJS CLI configuration
├── package.json            # Dependencies and scripts
├── tsconfig.json           # TypeScript configuration
├── tsconfig.build.json     # TypeScript build configuration
└── README.md               # Project documentation

HTTP Request
    ↓
main.ts (server starts)
    ↓
app.module.ts (module loaded)
    ↓
app.controller.ts (route matched)
    ↓
app.service.ts (business logic executed)
    ↓
Response sent back

import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

// @Module() is a class decorator that tells NestJS: "This class defines
// a module." The metadata object describes the module's boundaries --
// what it owns, what it needs, and what it shares.
@Module({
  controllers: [UsersController],  // The "reception desk" -- handles incoming HTTP requests
  providers: [UsersService],       // The "staff" -- services available for injection within this module
  exports: [UsersService],          // The "public API" -- what other modules can use when they import this one
})
export class UsersModule {}

// users/users.module.ts
@Module({
  controllers: [UsersController],
  providers: [UsersService, UserRepository],
  exports: [UsersService],  // Export so other modules can use UsersService
})
export class UsersModule {}

// app.module.ts
@Module({
  imports: [UsersModule],  // Import UsersModule to use its exported providers
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

import { Controller, Get, Post, Body, Param } from '@nestjs/common';
import { UsersService } from './users.service';

// @Controller('users') sets the base route prefix. Every method decorator
// below builds on this, so @Get() becomes GET /users, @Get(':id') becomes
// GET /users/:id, and so on.
@Controller('users')
export class UsersController {
  // NestJS sees UsersService in the constructor and automatically injects
  // the singleton instance. You never call "new UsersService()" yourself.
  // The 'private readonly' shorthand both declares and assigns the property.
  constructor(private readonly usersService: UsersService) {}

  @Get()  // GET /users -- returns all users
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')  // GET /users/:id -- the colon means this segment is dynamic
  findOne(@Param('id') id: string) {
    // @Param('id') extracts the :id segment from the URL.
    // Note: it arrives as a string. Use ParseIntPipe for automatic conversion.
    return this.usersService.findOne(id);
  }

  @Post()  // POST /users -- creates a new user from the request body
  create(@Body() createUserDto: CreateUserDto) {
    // @Body() extracts and deserializes the JSON request body into
    // a CreateUserDto instance. With ValidationPipe enabled globally,
    // this also validates the data before your code ever runs.
    return this.usersService.create(createUserDto);
  }
}

import { Injectable } from '@nestjs/common';

// @Injectable() registers this class with the NestJS DI container.
// Without it, NestJS cannot resolve or inject this class -- you will
// get a cryptic "Nest can't resolve dependencies" error at startup.
@Injectable()
export class UsersService {
  // In-memory data for demonstration. In production, this would be
  // replaced by a repository that talks to a real database.
  private users = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
  ];

  findAll() {
    return this.users;
  }

  findOne(id: number) {
    return this.users.find(user => user.id === id);
  }

  create(userData: { name: string; email: string }) {
    // WARNING: Using array length + 1 for IDs is fine for demos but
    // will produce duplicates after deletions. In production, use
    // auto-incrementing database IDs or UUIDs.
    const newUser = {
      id: this.users.length + 1,
      ...userData,
    };
    this.users.push(newUser);
    return newUser;
  }
}

Client Request
    ↓
Controller (receives request, extracts data)
    ↓
Service (business logic, data processing)
    ↓
Repository/Database (data persistence)
    ↓
Service (processes data)
    ↓
Controller (formats response)
    ↓
Client Response

@Controller('users')     // Class decorator
export class UsersController {
  @Get(':id')            // Method decorator
  findOne(
    @Param('id') id: string  // Parameter decorator
  ) {}
}

// A simple decorator is just a function
function Log(target: any, propertyKey: string, descriptor: PropertyDescriptor) {
  const originalMethod = descriptor.value;
  
  descriptor.value = function (...args: any[]) {
    console.log(`Calling ${propertyKey} with:`, args);
    return originalMethod.apply(this, args);
  };
}

class Example {
  @Log
  sayHello(name: string) {
    return `Hello, ${name}!`;
  }
}

// When you write this:
@Injectable()
export class UsersService {
  constructor(private db: DatabaseService) {}
}

// TypeScript compiles it to something like:
Reflect.defineMetadata('design:paramtypes', [DatabaseService], UsersService);

1. NestJS sees @Injectable() decorator
       ↓
2. Reflect.getMetadata('design:paramtypes', UsersService)
       ↓
3. Returns: [DatabaseService]
       ↓
4. NestJS creates DatabaseService instance (or gets from container)
       ↓
5. NestJS creates UsersService with DatabaseService injected

import { createParamDecorator, ExecutionContext } from '@nestjs/common';

// Custom parameter decorator to get current user
export const CurrentUser = createParamDecorator(
  (data: unknown, ctx: ExecutionContext) => {
    const request = ctx.switchToHttp().getRequest();
    return request.user;
  },
);

// Usage
@Get('profile')
getProfile(@CurrentUser() user: User) {
  return user;
}

import { NestFactory } from '@nestjs/core';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(3000);
}
bootstrap();

import { NestFactory } from '@nestjs/core';
import { ValidationPipe } from '@nestjs/common';
import { AppModule } from './app.module';

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  
  // Enable CORS
  app.enableCors();
  
  // Global validation pipe
  app.useGlobalPipes(new ValidationPipe({
    whitelist: true,        // Strip properties that don't have decorators
    forbidNonWhitelisted: true,  // Throw error if non-whitelisted properties exist
    transform: true,        // Automatically transform payloads to DTO instances
    transformOptions: {
      enableImplicitConversion: true,  // Enable implicit type conversion
    },
  }));
  
  // Global prefix for all routes
  app.setGlobalPrefix('api');
  
  const port = process.env.PORT || 3000;
  await app.listen(port);
  
  console.log(`Application is running on: http://localhost:${port}`);
}
bootstrap();

main.ts
    ↓
NestFactory.create(AppModule)
    ↓
AppModule loaded
    ↓
Imported modules loaded
    ↓
Providers instantiated
    ↓
Controllers registered
    ↓
Routes mapped
    ↓
HTTP Server listening
    ↓
Ready to handle requests

# Generate a module
nest generate module users
# or shorthand: nest g mo users

# Generate a controller
nest generate controller users
# or shorthand: nest g co users

# Generate a service
nest generate service users
# or shorthand: nest g s users

// users/dto/create-user.dto.ts
import { IsString, IsEmail, MinLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  name: string;

  @IsEmail()
  email: string;
}

// users/users.service.ts
import { Injectable, NotFoundException } from '@nestjs/common';
import { CreateUserDto } from './dto/create-user.dto';

@Injectable()
export class UsersService {
  private users = [
    { id: 1, name: 'Alice', email: 'alice@example.com' },
    { id: 2, name: 'Bob', email: 'bob@example.com' },
  ];

  findAll() {
    return this.users;
  }

  findOne(id: number) {
    const user = this.users.find(u => u.id === id);
    if (!user) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    return user;
  }

  create(createUserDto: CreateUserDto) {
    const id = this.users.length + 1;
    const user = { id, ...createUserDto };
    this.users.push(user);
    return user;
  }

  update(id: number, updateUserDto: Partial<CreateUserDto>) {
    const user = this.findOne(id);  // Throws if not found
    Object.assign(user, updateUserDto);
    return user;
  }

  remove(id: number) {
    const index = this.users.findIndex(u => u.id === id);
    if (index === -1) {
      throw new NotFoundException(`User with ID ${id} not found`);
    }
    this.users.splice(index, 1);
    return { message: `User with ID ${id} deleted` };
  }
}

// users/users.controller.ts
import {
  Controller,
  Get,
  Post,
  Put,
  Delete,
  Body,
  Param,
  ParseIntPipe,
} from '@nestjs/common';
import { UsersService } from './users.service';
import { CreateUserDto } from './dto/create-user.dto';

@Controller('users')
export class UsersController {
  constructor(private readonly usersService: UsersService) {}

  @Get()
  findAll() {
    return this.usersService.findAll();
  }

  @Get(':id')
  findOne(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.findOne(id);
  }

  @Post()
  create(@Body() createUserDto: CreateUserDto) {
    return this.usersService.create(createUserDto);
  }

  @Put(':id')
  update(
    @Param('id', ParseIntPipe) id: number,
    @Body() updateUserDto: Partial<CreateUserDto>,
  ) {
    return this.usersService.update(id, updateUserDto);
  }

  @Delete(':id')
  remove(@Param('id', ParseIntPipe) id: number) {
    return this.usersService.remove(id);
  }
}

// users/users.module.ts
import { Module } from '@nestjs/common';
import { UsersController } from './users.controller';
import { UsersService } from './users.service';

@Module({
  controllers: [UsersController],
  providers: [UsersService],
  exports: [UsersService],  // Export if other modules need UsersService
})
export class UsersModule {}

// app.module.ts
import { Module } from '@nestjs/common';
import { AppController } from './app.controller';
import { AppService } from './app.service';
import { UsersModule } from './users/users.module';

@Module({
  imports: [UsersModule],  // Import UsersModule
  controllers: [AppController],
  providers: [AppService],
})
export class AppModule {}

# Get all users
curl http://localhost:3000/users

# Get user by ID
curl http://localhost:3000/users/1

# Create a user
curl -X POST http://localhost:3000/users \
  -H "Content-Type: application/json" \
  -d '{"name": "Charlie", "email": "charlie@example.com"}'

# Update a user
curl -X PUT http://localhost:3000/users/1 \
  -H "Content-Type: application/json" \
  -d '{"name": "Alice Updated"}'

# Delete a user
curl -X DELETE http://localhost:3000/users/1

src/
├── users/
│   ├── dto/
│   │   ├── create-user.dto.ts
│   │   └── update-user.dto.ts
│   ├── users.controller.ts
│   ├── users.service.ts
│   └── users.module.ts
├── auth/
│   └── ...
└── app.module.ts

import { IsString, IsEmail, MinLength, MaxLength } from 'class-validator';

export class CreateUserDto {
  @IsString()
  @MinLength(2)
  @MaxLength(50)
  name: string;

  @IsEmail()
  email: string;
}

// ❌ Bad: Business logic in controller
@Post()
create(@Body() dto: CreateUserDto) {
  if (dto.email.includes('@')) {
    // validation logic
  }
  // business logic
  return { ... };
}

// ✅ Good: Controller delegates to service
@Post()
create(@Body() dto: CreateUserDto) {
  return this.usersService.create(dto);
}

// ❌ Bad
const port = 3000;

// ✅ Good
const port = process.env.PORT || 3000;

# Generate resources
nest g resource users

# Generate a guard
nest g guard auth

# Generate an interceptor
nest g interceptor logging

npm install @nestjs/swagger

import { NotFoundException, BadRequestException } from '@nestjs/common';

if (!user) {
  throw new NotFoundException('User not found');
}

@Controller('users')
export class UsersController {
  @Get('search')        // Must come BEFORE :id, or 'search' is treated as an id
  search(@Query('q') q: string) { ... }

  @Get(':id')           // Catches everything not matched above
  findOne(@Param('id', ParseIntPipe) id: number) { ... }
}

// ❌ Bad: Missing @Injectable() -- NestJS cannot manage this class
export class UsersService {
  // ...
}

// ✅ Good: Decorator tells NestJS to track this class in the DI container
@Injectable()
export class UsersService {
  // ...
}

// ❌ Bad: Module A imports Module B, Module B imports Module A
// This causes a runtime error unless you use forwardRef()

// ✅ Better: Use forwardRef() as a last resort
@Module({
  imports: [forwardRef(() => AuthModule)],
})
export class UsersModule {}

// ✅ Best: Restructure to eliminate the cycle entirely

// ❌ Bad: Service not exported, other modules get injection errors
@Module({
  providers: [UsersService],
})

// ✅ Good: Export what other modules need
@Module({
  providers: [UsersService],
  exports: [UsersService],
})

// ❌ Bad: id is a string, comparison with number fails silently
@Get(':id')
findOne(@Param('id') id: string) {
  return this.usersService.findOne(id);  // comparing string to number
}

// ✅ Good: ParseIntPipe converts and validates in one step
@Get(':id')
findOne(@Param('id', ParseIntPipe) id: number) {
  return this.usersService.findOne(id);  // id is guaranteed to be a number
}