¿Qué es NestJS y por qué lo necesitas? Setup con Docker desde cero

Primer post de una serie larga. Pero larga larga! Porque vamos a aprender NestJS desde cero absoluto hasta montar una arquitectura enterprise con microservicios, CQRS, colas, WebSockets y todo lo que nos podamos imaginar. Y todo con Docker, todo tipado con TypeScript a fuego y siguiendo la documentación oficial al dedillo.

¿Por qué NestJS? ejejejeje Pues porque me hace falta machacarlo para tenerlo bien fresco y porque aparentemente se está pidiendo mucho en ofertas de trabajo, así que vamos a echarle un ojito a ver si nos gusta.

EA, vamos al lío.

---

1. Express está muy bien, pero…

Si vienes de Express, sabes que es una maravilla para montar algo rápido, cuatro líneas mal tirás y tienes un servidor corriendo. El problema viene cuando el proyecto crece, y crece un montón!

Con Express a pelo no tienes ninguna estructura definida y cada desarrollador organiza las carpetas como le apetece. Uno mete los controllers en /routes, otro en /api, otro mezcla todo en un index.js de 3000 líneas. No hay ninguna estructura o patrón definido de forma oficial, cada uno se lo guisa como quiere, y si te toca mantener un proyecto de Express vas a tener que dedicarle un tiempo a ver como se está organizando y donde está cada cosa.

Y ojo que no estoy diciendo que Express sea malo, para nada! Express es la base de NestJS (literalmente corre por debajo). Lo que quiero decir es que NestJS te da estructura, convenciones y herramientas que con Express tendrías que montar tú a mano.

---

2. ¿Qué es NestJS exactamente?

Vale pavo, ¿pero qué es NestJS? NestJS 💡 NestJS Framework progresivo de Node.js para construir aplicaciones del lado del servidor eficientes y escalables. Usa TypeScript por defecto, sigue una arquitectura modular inspirada en Angular y corre sobre Express o Fastify. Más info → es un framework para construir aplicaciones backend con Node.js. Está escrito en TypeScript, usa decoradores para casi todo y tiene una arquitectura modular que te conduce a organizar el código de una manera limpia y mantenible.

Algunos detalles importantes sobre NestJS:

• Usa Express por debajo (by default). También puedes usar Fastify Fastify Framework web de Node.js enfocado en el rendimiento. Alternativa a Express con menor overhead y mayor throughput. si necesitas más rendimiento, pero para empezar vamos con Express que es lo que conoce todo el mundo.
• La arquitectura está inspirada en Angular. Si vienes de Angular te vas a sentir bastante cómodo. Si no, tranqui, que yo tampoco.
• Combina OOP, FP y FRP. Programación Orientada a Objetos con clases y decoradores, pero también patrones funcionales y reactivos con RxJS RxJS Librería de programación reactiva para JavaScript. NestJS la usa internamente para manejar flujos asíncronos con Observables. y olé.
• Inyección de dependencias de serie. No necesitas instalar nada extra, viene integrado en el core.
• Todo es tipado. TypeScript de serie, interfaces, DTOs, decoradores tipados… Olvidate del any.

Un ojito rápido a la arquitectura

NestJS organiza todo en tres conceptos fundamentales:

En los próximos posts de la serie vamos a profundizar en cada uno de estos conceptos. Hoy nos centramos en montar el entorno y que todo funcione.

---

3. Requisitos previos

Para seguir esta serie necesitas:

• Docker y Docker Compose instalados en tu máquina, nada más. No necesitas Node.js instalado en local porque vamos a usar contenedores Docker para todo.
• Conocimientos básicos de TypeScript. Si no los tienes, pásate por la serie de TypeScript que ya tiene cinco posts cubriendo desde cero hasta tipos avanzados.
• Un IDE. Con VS Code vas sobrado y con la extensión de NestJS lo petas porque te va a hacer la vida más fácil.

---

4. Montando el entorno con Docker

No vas a instalar Node.js en tu máquina. Nada de ensuciar tu sistema con diferentes versiones globales. Todo va a ir en contenedores. Así cualquiera que clone el repo tiene exactamente el mismo entorno, da igual si usa Windows, Mac o Linux.

4.1. Crear el proyecto

Primero creamos la carpeta del proyecto y generamos el proyecto de NestJS usando el CLI directamente desde Docker, sin instalar nada en local:

¿Qué acabamos de hacer? Usar un contenedor temporal de Node 22 Alpine para ejecutar el CLI de NestJS y generar el proyecto. El flag --strict activa las opciones más estrictas de TypeScript, que es lo que queremos, tipado fuerte a fuego. El --rm borra el contenedor cuando termina, así no deja basura.

Ojito aquí: como el contenedor de Docker corre como root, los archivos generados pertenecen al usuario root de tu máquina y no vas a poder editarlos. Para arreglar esto, cambiamos el propietario de la carpeta a tu usuario:

sudo chown -R $USER:$USER api/

E YA. Ahora ya puedes crear y editar archivos dentro de api/ sin problemas. Esto solo hay que hacerlo una vez, cuando generas el proyecto.

4.2. El Dockerfile

Dentro de la carpeta api/ que nos ha generado el CLI, creamos el Dockerfile para desarrollo:

# Dockerfile
FROM node:22-alpine

WORKDIR /app

# Copiamos los archivos de dependencias primero (para aprovechar la caché de Docker)
COPY package*.json ./

RUN npm ci

# Copiamos el resto del código
COPY . .

# Puerto que expone NestJS
EXPOSE 3000

# Arrancamos en modo watch (hot reload)
CMD ["npm", "run", "start:dev"]

Aquí usamos npm ci en vez de npm install porque ci instala exactamente las versiones del package-lock.json, sin sorpresas. Y arrancamos con start:dev que activa el hot reload hot reload Modo de desarrollo que reinicia automáticamente el servidor cada vez que guardas un cambio en el código. No tienes que parar y volver a arrancar la aplicación manualmente. para que cada vez que guardes un archivo, el servidor se reinicie solo.

4.3. Docker Compose

En la raíz del proyecto (nestjs-course/), creamos el docker-compose.yml:

services:
    api:
        build:
            context: ./api
            dockerfile: Dockerfile
        ports:
            - '3000:3000'
        volumes:
            - ./api:/app
            - /app/node_modules
        environment:
            - NODE_ENV=development

Para trabajar bien con Docker, la cosa está en los volumes. Montamos ./api:/app para que los cambios que hagas en tu editor se reflejen dentro del contenedor al momento. Pero usamos /app/node_modules como volumen anónimo para que los node_modules del contenedor no se machaquen con los de tu máquina local si los tuvieras. Es un patrón clásico de Docker para desarrollo con Node.js.

4.4. Arrancamos

EA, ya tienes NestJS corriendo en Docker y sin instalar Node en tu máquina. Si abres http://localhost:3000 en el navegador, verás el Hello World!.

---

5. Entendiendo la estructura del proyecto

Vamos a cotillear que nos ha generado el CLI y con qué estructura que aquí no hay nada hecho a lo loco.

api/
├── src/
│   ├── app.controller.ts        # Controller: recibe peticiones HTTP
│   ├── app.controller.spec.ts   # Tests del controller
│   ├── app.module.ts            # Módulo raíz: une todo
│   ├── app.service.ts           # Service: lógica de negocio
│   └── main.ts                  # Punto de entrada de la aplicación
├── test/
│   ├── app.e2e-spec.ts          # Tests end-to-end
│   └── jest-e2e.json            # Config de Jest para E2E
├── Dockerfile
├── nest-cli.json                # Configuración del CLI de Nest
├── package.json
├── tsconfig.json                # Config de TypeScript
└── tsconfig.build.json          # Config de TypeScript para build

Solo 5 archivos en src/. Minimalista y aesthetic o como se diga, todo muy claro. Vamos a ver qué hace cada uno.

---

6. De main.ts al Hello World

6.1. main.ts — El punto de entrada

Todo empieza aquí, este es el archivo que arranca la aplicación:

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

async function bootstrap(): Promise<void> {
    const app = await NestFactory.create(AppModule);
    await app.listen(process.env.PORT ?? 3000);
}
bootstrap();

NestFactory.create() recibe el módulo raíz de la aplicación y monta todo el árbol de dependencias, es como el arranque del motor. Llamas a bootstrap(), NestJS escanea todos los módulos, resuelve las dependencias, registra los controllers y levanta el servidor en el puerto 3000 o el que tengas en la variable de entorno PORT.

6.2. app.module.ts — El módulo raíz

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

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

El decorador @Module() le dice a NestJS:

• imports: otros módulos que este módulo necesita (ahora vacío, pero aquí irán por ejemplo modules como TypeOrmModule, AuthModule, etc.).
• controllers: los controllers que maneja este módulo.
• providers: los services y otros providers disponibles en este módulo.

Esto es el centro de la arquitectura modular 💡 arquitectura modular Patrón de diseño donde la aplicación se divide en módulos independientes, cada uno responsable de una funcionalidad concreta. Permite escalar, testear y mantener el código de forma ordenada. de NestJS. Cada funcionalidad que vayas añadiendo será un módulo nuevo que se importa aquí.

6.3. app.controller.ts — El controller

// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService } from './app.service';

@Controller()
export class AppController {
    constructor(private readonly appService: AppService) {}

    @Get()
    getHello(): string {
        return this.appService.getHello();
    }
}

Varias cosas importantes aquí:

• @Controller() es un decorador que convierte la clase en un controller de NestJS. Sin prefijo, así que responde en la raíz /.
• @Get() mapea el método getHello() a peticiones GET en /.
• El constructor(private readonly appService: AppService) es inyección de dependencias 💡 inyección de dependencias Patrón de diseño donde una clase recibe sus dependencias desde fuera en vez de crearlas ella misma. NestJS lo hace automáticamente a través del constructor: tú declaras el tipo y NestJS te pasa la instancia. Más info → . NestJS ve que el controller necesita un AppService, busca una instancia en el contenedor de dependencias y se la pasa automáticamente. Tú no haces new AppService() en ningún lado.
• El método devuelve string explícitamente, respuesta tipada.

6.4. app.service.ts — El service

// src/app.service.ts
import { Injectable } from '@nestjs/common';

@Injectable()
export class AppService {
    getHello(): string {
        return 'Hello World!';
    }
}

El decorador @Injectable() marca la clase como un provider que NestJS puede inyectar donde haga falta. La lógica de negocio vive aquí, no en el controller. El controller solo recibe la petición, llama al service y devuelve la respuesta, así conseguimos una buena separacion de responsabilidades.

El flujo completo

Cuando haces GET http://localhost:3000, esto es lo que pasa por debajo:

---

7. Tu primer endpoint tipado propio

El Hello World está muy bien pero vamos a hacer algo un poco más real, como añadir un endpoint que devuelva información de la API. Editamos los archivos que ya tenemos:

// src/app.service.ts
import { Injectable } from '@nestjs/common';

export interface ApiInfo {
    name: string;
    version: string;
    description: string;
    status: 'running' | 'maintenance';
}

@Injectable()
export class AppService {
    getHello(): string {
        return 'Hello World!';
    }

    getApiInfo(): ApiInfo {
        return {
            name: 'NestJS Course API',
            version: '1.0.0',
            description: 'API del curso de NestJS desde cero hasta enterprise',
            status: 'running',
        };
    }
}

Fíjate que hemos definido una interfaz ApiInfo exportada con un tipo literal para status que solo puede ser 'running' o 'maintenance'. Si intentas devolver otro valor, TypeScript te pega. La exportamos porque el controller necesita poder referenciar ese tipo.

Ahora añadimos la ruta en el controller:

// src/app.controller.ts
import { Controller, Get } from '@nestjs/common';
import { AppService, type ApiInfo } from './app.service';

@Controller()
export class AppController {
    constructor(private readonly appService: AppService) {}

    @Get()
    getHello(): string {
        return this.appService.getHello();
    }

    @Get('info')
    getApiInfo(): ApiInfo {
        return this.appService.getApiInfo();
    }
}

Ahora, si haces curl http://localhost:3000/info obtienes:

{
    "name": "NestJS Course API",
    "version": "1.0.0",
    "description": "API del curso de NestJS desde cero hasta enterprise",
    "status": "running"
}

NestJS ha serializado automáticamente el objeto a JSON y ha puesto el Content-Type: application/json. No has tenido que hacer res.json() ni nada. Devuelves un objeto y NestJS se encarga del resto.

---

8. Comandos útiles del CLI de NestJS

El Nest CLI 💡 Nest CLI Herramienta de línea de comandos de NestJS para generar componentes (controllers, services, modules, etc.), compilar y servir la aplicación. Se instala con npm i -g @nestjs/cli. Más info → es una herramienta brutal que te genera código siguiendo las convenciones del framework. Dentro del contenedor puedes ejecutar:

# Generar un nuevo módulo
docker compose exec api npx nest g module users

# Generar un controller
docker compose exec api npx nest g controller users

# Generar un service
docker compose exec api npx nest g service users

# Generar un CRUD resource completo (controller + service + module + DTOs)
docker compose exec api npx nest g resource users

El comando nest g resource es genial. Te genera un módulo completo con CRUD, DTOs y todo enchufado. Lo veremos en detalle en el próximo post cuando hablemos de Controllers y Routing.

---

9. Recapitulando

En el próximo post de la serie vamos a meternos de lleno con los Controllers y el Routing. Veremos todos los decoradores de rutas, cómo manejar parámetros, query strings, body, headers, y cómo organizar las rutas de tu API de forma profesional.

EA, nos vemos en los bares!! 🍺

---

Pon a prueba lo aprendido