Introducción e instalación NestJS

¿Qué es NestJS y por qué deberías usarlo?

NestJS es un framework progresivo de Node.js para construir aplicaciones de lado del servidor eficientes, escalables y mantenibles. Está escrito en TypeScript y combina elementos de la Programación Orientada a Objetos (POO), Programación Funcional Reactiva (PFR) y elementos de la Programación Funcional.

NestJS se inspira en Angular y adopta muchas de sus buenas prácticas, lo que facilita la integración entre ambos.

¿Por qué elegir NestJS?

• Estructura y Modularidad: A diferencia de frameworks más minimalistas como Express, NestJS te guía hacia una arquitectura robusta y organizada, similar a la de frameworks de frontend como Angular. Esto es ideal para proyectos grandes y equipos.
• TypeScript por defecto: Aprovecha todas las ventajas de TypeScript: tipado estático, autocompletado, detección de errores en tiempo de desarrollo y una mejor experiencia de refactorización.
• Rendimiento: Está construido sobre servidores HTTP robustos como Express o Fastify, lo que le permite ofrecer un alto rendimiento.
• Comunidad y Documentación: Cuenta con una comunidad creciente y una documentación oficial excepcional, lo que facilita el aprendizaje y la resolución de dudas.
• Inyección de Dependencias (DI): Uno de sus pilares fundamentales. NestJS se encarga de gestionar las dependencias de tu aplicación de forma automática, haciendo que el código sea más testeable y desacoplado.
• Ecosistema Rico: Ofrece módulos integrados para trabajar con bases de datos (TypeORM, Mongoose), GraphQL, WebSockets, microservicios, autenticación y mucho más.

En resumen, NestJS te ofrece las herramientas y la estructura para crear aplicaciones de Node.js de nivel empresarial, con un enfoque en la escalabilidad, la mantenibilidad y la productividad del desarrollador.

Instalación

Para instalar y trabajar con NestJS, necesitas tener lo siguiente en tu sistema:

• Node.js (versión 16 o superior): Es el entorno de ejecución para JavaScript fuera del navegador. Puedes descargarlo desde nodejs.org.
• npm o Yarn: Son gestores de paquetes que se instalan junto con Node.js. Usaremos npm en nuestros ejemplos, pero puedes usar yarn si lo prefieres.
• Editor de Código: Te recomendamos Visual Studio Code (VS Code) por su excelente soporte para TypeScript y las extensiones útiles para desarrollo con Node.js y NestJS.
• Postman o Insomnia: Herramientas para probar tus APIs enviando peticiones HTTP. Son muy útiles para el desarrollo backend.

Pasos para la instalación de NestJS

Instalación del CLI de NestJS:

NestJS viene con una potente interfaz de línea de comandos (CLI) que te permite generar proyectos, módulos, controladores y servicios de forma rápida, agilizando mucho el desarrollo.

Para instalar el NestJS CLI de forma global en tu sistema, abre tu terminal o línea de comandos y ejecuta el siguiente comando:

npm install -g @nestjs/cli

Después de la instalación, se puede verificar la versión del CLI de NestJS con el siguiente comando:

nest --version

Creación de un nuevo proyecto NestJS:

Una vez que el CLI de NestJS esté instalado, se puede crear un nuevo proyecto utilizando el siguiente comando:

nest new nombre-del-proyecto

El CLI te hará una pregunta sobre qué gestor de paquetes quieres usar (npm, yarn, pnpm). Selecciona npm (presiona Enter).

NestJS CLI se encargará de:

• Crear una nueva carpeta con el nombre de tu proyecto.
• Descargar e instalar todas las dependencias necesarias.
• Configurar una estructura de proyecto básica.

Estructura de proyectos NestJS

Un proyecto Nest típico tiene la siguiente estructura:

my-nestjs-project/
|-- src/
|   |-- app.controller.ts
|   |-- app.module.ts
|   |-- app.service.ts
|   |-- main.ts
|-- test/
|-- .gitignore
|-- nest-cli.json
|-- package.json
|-- tsconfig.build.json
|-- tsconfig.json

• src/: Contiene el código fuente de la aplicación.
• app.controller.ts: Un controlador básico que maneja las rutas y acciones HTTP.
• app.module.ts: El módulo raíz que organiza las dependencias y funcionalidades de la aplicación.
• app.service.ts: Un servicio básico que contiene la lógica de negocio.
• main.ts: El punto de entrada de la aplicación.
• test/: Contiene los archivos de prueba.
• nest-cli.json: Configuración del CLI de NestJS.
• package.json: Contiene las dependencias del proyecto y scripts.
• tsconfig.build.json y tsconfig.json: Configuración de TypeScript.

Accede al directorio del proyecto desde VSCode: Una vez que el proceso termine, entra a la carpeta de tu nuevo proyecto.

Inicia la aplicación: Para arrancar tu aplicación NestJS, usa el siguiente comando:

npm run start:dev

Este comando inicia la aplicación en modo desarrollo, lo que significa que se reiniciará automáticamente cada vez que guardes cambios en tu código.

Verifica en el navegador: Abre tu navegador web y visita http://localhost:3000. Deberías ver un mensaje simple como "Hello World!" o "Welcome to NestJS!".

Versiones recomendadas para 2026

NestJS evoluciona junto con el ecosistema Node.js. Las versiones soportadas y recomendadas para nuevos proyectos:

| Componente | Versión | Notas | |------------|---------|-------| | Node.js | 22 LTS (Iron) o 24 LTS | EOL Node.js 18 en abril 2025; usar 22 mínimo | | TypeScript | 5.6+ | Decoradores estándar, using, satisfies | | NestJS | 11.x | Express 5 / Fastify 5, AsyncLocalStorage nativo | | npm | 10+ | Soporte ESM, lockfile v3 | | pnpm | 9+ | Recomendado en monorepos por velocidad |

Verificación rápida con node --version && nest --version && tsc --version. Si la versión de Node es inferior a 22, instala con nvm install 22 && nvm use 22 (Linux/Mac) o usa volta (multiplataforma) para fijar la versión por proyecto.

Configuración inicial recomendada

Tras nest new, conviene ajustar varios ficheros antes del primer commit:

tsconfig.json con strict habilitado

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "noImplicitAny": true,
    "strictNullChecks": true,
    "noUncheckedIndexedAccess": true,
    "experimentalDecorators": true,
    "emitDecoratorMetadata": true,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "outDir": "./dist",
    "baseUrl": "./",
    "paths": { "@app/*": ["src/*"] }
  }
}

noUncheckedIndexedAccess: true hace que array[i] devuelva T | undefined, forzando comprobación de límites. Es la mejor red de seguridad contra los Cannot read property of undefined en producción.

Scripts de calidad

{
  "scripts": {
    "build": "nest build",
    "start:dev": "nest start --watch",
    "start:debug": "nest start --debug --watch",
    "start:prod": "node dist/main",
    "lint": "eslint \"{src,apps,libs,test}/**/*.ts\" --fix",
    "format": "prettier --write \"src/**/*.ts\" \"test/**/*.ts\"",
    "test": "jest",
    "test:cov": "jest --coverage",
    "test:e2e": "jest --config ./test/jest-e2e.json",
    "typecheck": "tsc --noEmit"
  }
}

Variables de entorno con @nestjs/config

npm i @nestjs/config

@Module({
  imports: [
    ConfigModule.forRoot({
      isGlobal: true,
      envFilePath: ['.env', '.env.local'],
      validationSchema: Joi.object({
        NODE_ENV: Joi.string().valid('development', 'production', 'test').default('development'),
        PORT: Joi.number().port().default(3000),
        DATABASE_URL: Joi.string().uri().required(),
        JWT_SECRET: Joi.string().min(32).required(),
      }),
    }),
  ],
})
export class AppModule {}

La validación con Joi (o Zod) se ejecuta al arrancar: si falta JWT_SECRET o tiene menos de 32 caracteres, el proceso aborta. Es la práctica enterprise estándar para evitar despliegues con configuración rota.

Estructura escalable de carpetas

Para proyectos enterprise, la estructura por features supera al árbol plano de scaffolding:

src/
|-- common/                # Pipes, guards, interceptors, decorators globales
|   |-- decorators/
|   |-- filters/
|   |-- interceptors/
|   `-- pipes/
|-- config/                # ConfigModule, esquemas Joi/Zod
|-- modules/
|   |-- auth/
|   |   |-- dto/
|   |   |-- strategies/
|   |   |-- auth.controller.ts
|   |   |-- auth.module.ts
|   |   `-- auth.service.ts
|   |-- users/
|   `-- products/
|-- shared/                # Utilidades transversales (loggers, helpers)
|-- app.module.ts
`-- main.ts

Cada feature es autocontenida y puede extraerse a un microservicio sin reescribir imports.

Solución de problemas frecuentes

• EACCES al instalar el CLI globalmente: usa nvm en lugar de Node del sistema o instala en local con npx @nestjs/cli new ....
• Errores de decoradores experimentales: comprobar emitDecoratorMetadata: true y experimentalDecorators: true en tsconfig.json. Necesario para que class-validator y TypeORM funcionen.
• Lentitud en nest start --watch: cambia el builder a SWC ("builder": "swc" en nest-cli.json). Reduce el tiempo de recompilación de 3-4s a 200ms.
• Errores ESM/CommonJS al importar paquetes nuevos: revisar "module": "NodeNext" y usar imports con extensión cuando el paquete es ESM-only.

Conclusión

Instalar y comenzar con NestJS es un proceso simple y directo. Utilizando el CLI de NestJS, se puede crear, gestionar y desarrollar aplicaciones del lado del servidor de manera eficiente. Con la configuración estricta de TypeScript, validación de variables de entorno y una estructura por features, el proyecto está listo para crecer hasta arquitecturas enterprise sin reescrituras costosas.