Conceptos básicos de NestJS

Q: ¿Puedo usar ESM con NestJS?

Sí, con "type": "module" y extensiones .js en las importaciones. Consulta la documentación de NestJS 11 ESM para conocer el estado actual de la compatibilidad.

10 ejemplos para entender el modelo mental de NestJS 11: 7 básicos y 3 intermedios.

Requisitos previos

npm i -g @nestjs/cli@11
nest new my-api --strict
cd my-api
npm pkg set type=module

Para patrones de DI y aspectos transversales, consulta Inyección de dependencias y Guards, Interceptors y Pipes.

Ejemplos básicos

1. Módulo, Controlador, Servicio

// users.module.ts
import { Module } from "@nestjs/common";
import { UsersController } from "./users.controller.js";
import { UsersService } from "./users.service.js";
 
@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// users.service.ts
import { Injectable } from "@nestjs/common";
 
@Injectable()
export class UsersService {
  findAll() {
    return [{ id: 1, name: "Ada Lovelace" }];
  }
}

// users.controller.ts
import { Controller, Get } from "@nestjs/common";
import { UsersService } from "./users.service.js";
 
@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
 
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Module agrupa controladores y proveedores relacionados
@Injectable marca una clase para DI
@Controller define el prefijo de la ruta; los métodos definen los verbos HTTP

2. Parámetros de ruta y cuerpo

import { Controller, Get, Post, Body, Param } from "@nestjs/common";
 
@Controller("users")
export class UsersController {
  @Get(":id")
  findOne(@Param("id") id: string) {
    return { id, name: "Ada" };
  }
 
  @Post()
  create(@Body() body: { name: string; email: string }) {
    return { id: "1", ...body };
  }
}

@Param("id") extrae parámetros de ruta
@Body() extrae el cuerpo de la solicitud (analizado por el adaptador subyacente)
Agrega ValidationPipe para validación automática

3. Módulo raíz y Bootstrap

// app.module.ts
import { Module } from "@nestjs/common";
import { UsersModule } from "./users/users.module.js";
 
@Module({
  imports: [UsersModule],
})
export class AppModule {}

// main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

AppModule es la raíz; importa módulos de características
NestFactory.create inicializa el contenedor de DI
Usa NestFactory.create(AppModule, new FastifyAdapter()) para rendimiento

4. Prefijo global

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");
  await app.listen(3000);
}

Todas las rutas tienen el prefijo /api/v1
Las comprobaciones de estado a menudo se excluyen: setGlobalPrefix("api", { exclude: ["health"] })

5. ValidationPipe

import { ValidationPipe } from "@nestjs/common";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
  await app.listen(3000);
}

import { IsEmail, IsString, MinLength } from "class-validator";
 
export class CreateUserDto {
  @IsString()
  @MinLength(1)
  name!: string;
 
  @IsEmail()
  email!: string;
}

whitelist: true elimina propiedades desconocidas
transform: true convierte objetos planos en instancias de clases DTO
Requiere class-validator y class-transformer

6. Filtros de excepción

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";
 
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();
    response.status(status).json(exception.getResponse());
  }
}

Los filtros capturan excepciones y dan forma a las respuestas de error
@Catch(HttpException) se aplica a excepciones HTTP
Se registra globalmente o por controlador

7. Configuración del entorno

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
 
@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true })],
})
export class AppModule {}

import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
 
@Injectable()
export class AppService {
  constructor(private config: ConfigService) {}
 
  getPort() {
    return this.config.get<number>("PORT", 3000);
  }
}

@nestjs/config carga archivos .env
ConfigService inyecta valores de entorno
Valida el entorno con Joi o Zod al inicio

Ejemplos intermedios

8. Adaptador Fastify

import { NestFactory } from "@nestjs/core";
import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ logger: true })
  );
  await app.listen({ port: 3000, host: "0.0.0.0" });
}
bootstrap();

El adaptador Fastify elimina la sobrecarga de Express
Consulta Realidad del rendimiento de NestJS

9. Exportaciones de módulos de características

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
 
@Module({
  imports: [UsersModule],
  controllers: [OrdersController],
})
export class OrdersModule {}
// OrdersController puede inyectar UsersService

exports hace que los proveedores estén disponibles para los módulos importadores
Sin exports, los proveedores son privados del módulo

10. Hooks del ciclo de vida

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
 
@Injectable()
export class DatabaseService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    console.log("Conectando a la base de datos...");
  }
 
  async onModuleDestroy() {
    console.log("Cerrando conexiones a la base de datos...");
  }
}

onModuleInit se ejecuta después de que se resuelven las dependencias del módulo
onModuleDestroy se ejecuta en el cierre elegante
Úsalo para la configuración y el desmontaje del pool de conexiones

Preguntas frecuentes

¿Cuándo debo elegir NestJS en lugar de Fastify?

NestJS cuando necesites DI, arquitectura modular, guards/interceptors y patrones de microservicios. Fastify para APIs ligeras. Consulta Lista de verificación para la selección de frameworks.

¿NestJS 11 está listo para producción?

Sí. NestJS 11 es compatible con los adaptadores Express 5 y Fastify 5 en Node 24 LTS.

¿NestJS requiere TypeScript?

Muy recomendable. NestJS está impulsado por decoradores y diseñado para TypeScript. JavaScript funciona, pero pierde la seguridad de tipos.

¿Cómo se compara NestJS con Spring Boot?

Modelo mental similar: módulos, DI, decoradores, guards. NestJS es el equivalente más cercano en Node.

¿Puedo usar ESM con NestJS?

Sí, con "type": "module" y extensiones .js en las importaciones. Consulta la documentación de NestJS 11 ESM para conocer el estado actual de la compatibilidad.

Relacionado

Inyección de dependencias - patrones de DI
Guards, Interceptors y Pipes - aspectos transversales
NestJS + Prisma/TypeORM - capa de datos
Conceptos básicos de Fastify - adaptador subyacente
Mejores prácticas de NestJS - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Requisitos previos

npm i -g @nestjs/cli@11
nest new my-api --strict
cd my-api
npm pkg set type=module

Para patrones de DI y aspectos transversales, consulta Inyección de dependencias y Guards, Interceptors y Pipes.

Ejemplos básicos

1. Módulo, Controlador, Servicio

// users.module.ts
import { Module } from "@nestjs/common";
import { UsersController } from "./users.controller.js";
import { UsersService } from "./users.service.js";
 
@Module({
  controllers: [UsersController],
  providers: [UsersService],
})
export class UsersModule {}

// users.service.ts
import { Injectable } from "@nestjs/common";
 
@Injectable()
export class UsersService {
  findAll() {
    return [{ id: 1, name: "Ada Lovelace" }];
  }
}

// users.controller.ts
import { Controller, Get } from "@nestjs/common";
import { UsersService } from "./users.service.js";
 
@Controller("users")
export class UsersController {
  constructor(private readonly usersService: UsersService) {}
 
  @Get()
  findAll() {
    return this.usersService.findAll();
  }
}

@Module agrupa controladores y proveedores relacionados
@Injectable marca una clase para DI
@Controller define el prefijo de la ruta; los métodos definen los verbos HTTP

2. Parámetros de ruta y cuerpo

import { Controller, Get, Post, Body, Param } from "@nestjs/common";
 
@Controller("users")
export class UsersController {
  @Get(":id")
  findOne(@Param("id") id: string) {
    return { id, name: "Ada" };
  }
 
  @Post()
  create(@Body() body: { name: string; email: string }) {
    return { id: "1", ...body };
  }
}

@Param("id") extrae parámetros de ruta
@Body() extrae el cuerpo de la solicitud (analizado por el adaptador subyacente)
Agrega ValidationPipe para validación automática

3. Módulo raíz y Bootstrap

// app.module.ts
import { Module } from "@nestjs/common";
import { UsersModule } from "./users/users.module.js";
 
@Module({
  imports: [UsersModule],
})
export class AppModule {}

// main.ts
import { NestFactory } from "@nestjs/core";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

AppModule es la raíz; importa módulos de características
NestFactory.create inicializa el contenedor de DI
Usa NestFactory.create(AppModule, new FastifyAdapter()) para rendimiento

4. Prefijo global

async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.setGlobalPrefix("api/v1");
  await app.listen(3000);
}

Todas las rutas tienen el prefijo /api/v1
Las comprobaciones de estado a menudo se excluyen: setGlobalPrefix("api", { exclude: ["health"] })

5. ValidationPipe

import { ValidationPipe } from "@nestjs/common";
 
async function bootstrap() {
  const app = await NestFactory.create(AppModule);
  app.useGlobalPipes(new ValidationPipe({ whitelist: true, transform: true }));
  await app.listen(3000);
}

import { IsEmail, IsString, MinLength } from "class-validator";
 
export class CreateUserDto {
  @IsString()
  @MinLength(1)
  name!: string;
 
  @IsEmail()
  email!: string;
}

whitelist: true elimina propiedades desconocidas
transform: true convierte objetos planos en instancias de clases DTO
Requiere class-validator y class-transformer

6. Filtros de excepción

import { ExceptionFilter, Catch, ArgumentsHost, HttpException } from "@nestjs/common";
 
@Catch(HttpException)
export class HttpExceptionFilter implements ExceptionFilter {
  catch(exception: HttpException, host: ArgumentsHost) {
    const ctx = host.switchToHttp();
    const response = ctx.getResponse();
    const status = exception.getStatus();
    response.status(status).json(exception.getResponse());
  }
}

Los filtros capturan excepciones y dan forma a las respuestas de error
@Catch(HttpException) se aplica a excepciones HTTP
Se registra globalmente o por controlador

7. Configuración del entorno

import { Module } from "@nestjs/common";
import { ConfigModule } from "@nestjs/config";
 
@Module({
  imports: [ConfigModule.forRoot({ isGlobal: true })],
})
export class AppModule {}

import { Injectable } from "@nestjs/common";
import { ConfigService } from "@nestjs/config";
 
@Injectable()
export class AppService {
  constructor(private config: ConfigService) {}
 
  getPort() {
    return this.config.get<number>("PORT", 3000);
  }
}

@nestjs/config carga archivos .env
ConfigService inyecta valores de entorno
Valida el entorno con Joi o Zod al inicio

Ejemplos intermedios

8. Adaptador Fastify

import { NestFactory } from "@nestjs/core";
import { FastifyAdapter, NestFastifyApplication } from "@nestjs/platform-fastify";
import { AppModule } from "./app.module.js";
 
async function bootstrap() {
  const app = await NestFactory.create<NestFastifyApplication>(
    AppModule,
    new FastifyAdapter({ logger: true })
  );
  await app.listen({ port: 3000, host: "0.0.0.0" });
}
bootstrap();

El adaptador Fastify elimina la sobrecarga de Express
Consulta Realidad del rendimiento de NestJS

9. Exportaciones de módulos de características

@Module({
  providers: [UsersService],
  exports: [UsersService],
})
export class UsersModule {}
 
@Module({
  imports: [UsersModule],
  controllers: [OrdersController],
})
export class OrdersModule {}
// OrdersController puede inyectar UsersService

exports hace que los proveedores estén disponibles para los módulos importadores
Sin exports, los proveedores son privados del módulo

10. Hooks del ciclo de vida

import { Injectable, OnModuleInit, OnModuleDestroy } from "@nestjs/common";
 
@Injectable()
export class DatabaseService implements OnModuleInit, OnModuleDestroy {
  async onModuleInit() {
    console.log("Conectando a la base de datos...");
  }
 
  async onModuleDestroy() {
    console.log("Cerrando conexiones a la base de datos...");
  }
}

onModuleInit se ejecuta después de que se resuelven las dependencias del módulo
onModuleDestroy se ejecuta en el cierre elegante
Úsalo para la configuración y el desmontaje del pool de conexiones

Preguntas frecuentes

¿Cuándo debo elegir NestJS en lugar de Fastify?

NestJS cuando necesites DI, arquitectura modular, guards/interceptors y patrones de microservicios. Fastify para APIs ligeras. Consulta Lista de verificación para la selección de frameworks.

¿NestJS 11 está listo para producción?

Sí. NestJS 11 es compatible con los adaptadores Express 5 y Fastify 5 en Node 24 LTS.

¿NestJS requiere TypeScript?

Muy recomendable. NestJS está impulsado por decoradores y diseñado para TypeScript. JavaScript funciona, pero pierde la seguridad de tipos.

¿Cómo se compara NestJS con Spring Boot?

Modelo mental similar: módulos, DI, decoradores, guards. NestJS es el equivalente más cercano en Node.

¿Puedo usar ESM con NestJS?

Sí, con "type": "module" y extensiones .js en las importaciones. Consulta la documentación de NestJS 11 ESM para conocer el estado actual de la compatibilidad.

Relacionado

Inyección de dependencias - patrones de DI
Guards, Interceptors y Pipes - aspectos transversales
NestJS + Prisma/TypeORM - capa de datos
Conceptos básicos de Fastify - adaptador subyacente
Mejores prácticas de NestJS - lista de verificación de la sección

Versiones de la pila: Esta página fue escrita para Node.js 24.18.0 (LTS activo), npm 10+, TypeScript 5.6+, Express 5, Fastify 5 y NestJS 11.

Conceptos básicos de NestJS

Buscar en la documentación

Conceptos básicos de NestJS