Comandos NestJS CLI

Introducción

La Interfaz de Línea de Comandos (CLI) de NestJS es una herramienta fundamental para los desarrolladores que trabajan con este framework. Permite generar y gestionar proyectos, módulos, servicios, controladores y otros componentes de manera eficiente, agilizando significativamente el proceso de desarrollo. En esta lección, exploraremos los comandos más utilizados de NestJS CLI, comprendiendo su propósito y aplicación práctica para facilitar la creación y estructuración de aplicaciones NestJS.

Inicialización de un Nuevo Proyecto: nest new

Como ya hemos visto, el comando nest new es el punto de partida para cualquier aplicación NestJS. Permite crear una nueva estructura de proyecto con todas las configuraciones básicas necesarias.

nest new nombre-del-proyecto

Generación de Componentes: nest generate (o nest g)

El comando nest generate (o su alias nest g) es una herramienta poderosa para crear los diferentes bloques de construcción de una aplicación NestJS. Permite generar módulos, controladores, servicios, guards, interceptors, pipes, filters, etc.

Sintaxis General:

nest generate <tipo-de-componente> <nombre-del-componente> [opciones]

a. Módulo:

nest g module nombre-del-modulo

b. Controlador:

nest g controller nombre-del-controlador

c. Servicio:

nest g service nombre-del-servicio

d. Recurso:

Un recurso genera un módulo, un controlador y un servicio, junto con sus archivos de prueba, preconfigurados para operaciones CRUD (Crear, Leer, Actualizar, Eliminar).

nest g resource nombre-del-producto

Ejecución de la aplicación

Una vez que el proyecto ha sido creado y configurado, se puede ejecutar utilizando el comando start:

nest start

Otros comandos útiles

Compilación

El comando nest build compila la aplicación NestJS para producción. Transpila el código TypeScript a JavaScript y genera los archivos de salida listos para ser desplegados.

nest build

Este comando creará una carpeta dist en la raíz del proyecto, conteniendo el código JavaScript transpilado.

Ejecución en modo de desarrollo

Para ejecutar la aplicación en modo de desarrollo, donde se reinicia automáticamente después de cada cambio:

nest start --watch

Pruebas

NestJS viene con soporte integrado para pruebas unitarias y de integración. El comando nest test ejecuta las pruebas definidas en el proyecto.

Para ejecutar las pruebas unitarias:

nest test

Información del Proyecto: nest info

El comando nest info proporciona información útil sobre el entorno del proyecto, incluyendo la versión de NestJS CLI, la versión de NestJS, la versión de Node.js, y el sistema operativo.

Sintaxis:

nest info

Este comando es útil para depurar problemas de compatibilidad o para proporcionar información al buscar soporte.

Resumen de Puntos Clave

• nest new: Crea un nuevo proyecto NestJS.
• nest generate (o nest g): Genera componentes como módulos, controladores, servicios, etc. Es fundamental para la modularidad y la organización del código.
• nest start: Inicia la aplicación en modo de desarrollo, con la opción --watch para recarga automática.
• nest build: Compila la aplicación para producción.
• nest test: Ejecuta las pruebas unitarias y de integración.
• nest info: Muestra información del entorno del proyecto.

Generadores avanzados y schematics

NestJS CLI usa el motor de schematics de Angular para generar archivos consistentes con la convención del framework. Los generadores g resource, g module, g service aceptan flags muy útiles en proyectos enterprise:

| Flag | Efecto | |------|--------| | --no-spec | No genera el archivo *.spec.ts (útil cuando el equipo tiene un setup propio de tests). | | --flat | Coloca los archivos en el directorio actual sin crear subcarpeta. | | --dry-run (-d) | Muestra qué archivos crearía sin tocar disco. Crítico para revisar antes de generar. | | --skip-import | No registra el componente en el módulo padre. | | -p <path> | Apunta el comando a otro proyecto en monorepo. |

Al ejecutar nest g resource users el CLI pregunta el transport (REST API, GraphQL code-first, GraphQL schema-first, Microservice, WebSockets) y si quieres CRUD entry-points generados. La elección define la plantilla del controller y los DTOs base. En proyectos GraphQL code-first, el CLI emite resolvers tipados con decoradores @Resolver, @Query, @Mutation y un esquema autogenerado a partir de las clases.

Monorepo con nest-cli.json

Cuando una organización mantiene varios microservicios NestJS conviene usar un monorepo. nest g app y nest g library permiten crear apps independientes y librerías compartidas dentro del mismo workspace. El archivo nest-cli.json declara los proyectos:

{
  "$schema": "https://json.schemastore.org/nest-cli",
  "monorepo": true,
  "root": "apps/api",
  "compilerOptions": {
    "deleteOutDir": true,
    "builder": "swc",
    "typeCheck": true
  },
  "projects": {
    "api": {
      "type": "application",
      "root": "apps/api",
      "entryFile": "main"
    },
    "worker": {
      "type": "application",
      "root": "apps/worker"
    },
    "shared": {
      "type": "library",
      "root": "libs/shared",
      "sourceRoot": "libs/shared/src"
    }
  }
}

Con esta estructura, comandos como nest start api, nest build worker o nest g service notifications -p shared operan sobre el proyecto correcto sin scripts custom. El builder swc reduce el tiempo de build entre 5x y 10x frente a tsc puro.

Plantillas y starters propios

Para acelerar la consistencia entre equipos, las consultoras IT suelen crear un starter corporativo (logging estructurado, error handling, OpenAPI, healthcheck, CI/CD) y publicarlo como repositorio plantilla. Variantes habituales:

• nest new my-app --strict activa strict: true en tsconfig.json desde el primer día.
• nest new my-app --package-manager pnpm fuerza pnpm para evitar mezclar gestores en el equipo.
• Schematic propio publicado en un paquete @empresa/nest-schematics que añade módulos opinados (auth, health, metrics) con nest g @empresa/nest-schematics:auth.

Comandos de mantenimiento y depuración

Más allá de los comandos de scaffolding, el CLI ofrece utilidades de mantenimiento:

# Ejecutar la aplicación con debugger en el puerto 9229
nest start --debug --watch

# Compilar con sourcemaps para depurar en producción con stack traces reales
nest build --sourceMap

# Ejecutar e2e tests con configuración aislada
nest test --e2e

# Listar comandos disponibles y sus opciones
nest --help
nest g --help

nest start --debug es esencial cuando se conecta VSCode con attach para colocar breakpoints en TypeScript directamente, sin transpilación intermedia. nest build --sourceMap permite que herramientas como Sentry mapeen el stack trace minificado a la línea original del archivo .ts.

Workflow recomendado en equipo

1. Convención de nombres: usar siempre kebab-case (user-profile) para que el CLI genere UserProfileController y UserProfileService. Evitar nombres con acentos o espacios.
2. Generar siempre con --dry-run la primera vez que aplicas un schematic nuevo en el repo para revisar exactamente qué archivos crea.
3. No mezclar nest g con cambios manuales en el mismo commit: separa la generación del CLI de las modificaciones de lógica para que el diff sea revisable.
4. Versionar nest-cli.json y tsconfig*.json con el resto del código. Son la fuente de verdad de cómo compila el equipo.
5. Pin de versión del CLI en package.json ("@nestjs/cli": "11.0.x") y ejecutar con npx nest para evitar que diferentes desarrolladores obtengan resultados distintos.