¿Cómo integrar TypeScript en un proyecto real con Node.js?

Integrar TypeScript en un proyecto Node.js significa configurar un entorno donde escribes código tipado, lo compilas a JavaScript y lo ejecutas con Node.

Esta lección te muestra el proceso completo paso a paso. Al terminar, tendrás una aplicación funcional lista para crecer.

Estructura de carpetas recomendada

Antes de escribir una sola línea de código, define cómo organizarás el proyecto. Una estructura clara evita confusión cuando el proyecto crece.

Usa esta organización estándar:

mi-proyecto/
├── src/
│   ├── tipos/
│   │   └── index.ts
│   ├── servicios/
│   │   └── productos.ts
│   ├── utilidades/
│   │   └── formato.ts
│   └── index.ts
├── dist/
├── package.json
└── tsconfig.json

src/ contiene todo tu código fuente en TypeScript. dist/ recibe los archivos JavaScript compilados. Nunca edites archivos dentro de dist/ directamente.

Inicializar el proyecto

Abre tu terminal y ejecuta estos comandos en orden:

mkdir mi-proyecto
cd mi-proyecto
npm init -y

Eso crea el archivo package.json con valores predeterminados. Después instala TypeScript y los tipos de Node:

npm install --save-dev typescript
npm install --save-dev @types/node

typescript es el compilador. @types/node proporciona los tipos de todas las funciones nativas de Node, como fs, path y console.

Finalmente, genera el archivo de configuración:

npx tsc --init

Eso crea un tsconfig.json con muchas opciones comentadas. Solo necesitas ajustar algunas.

Configurar tsconfig.json

Abre el archivo tsconfig.json y deja activas estas opciones clave:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "moduleResolution": "node",
    "rootDir": "./src",
    "outDir": "./dist",
    "strict": true,
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Configurar scripts en package.json

Agrega estos scripts dentro de tu package.json:

"scripts": {
  "build": "tsc",
  "start": "node dist/index.js",
  "dev": "tsc --watch"
}

build compila todos los archivos TypeScript. start ejecuta el resultado compilado. dev observa cambios y recompila automáticamente mientras desarrollas.

Construir una aplicación de ejemplo

Vamos a construir una pequeña aplicación que calcula el total de un pedido de una tienda. El ejemplo usa precios en pesos, como los de Liverpool o Mercado Libre.

Paso 1: Define los tipos

Crea el archivo src/tipos/index.ts:

export interface Producto {
  nombre: string;
  precio: number;
  cantidad: number;
}

export interface Pedido {
  id: string;
  cliente: string;
  productos: Producto[];
}

Paso 2: Crea el servicio de productos

Crea el archivo src/servicios/productos.ts:

import { Pedido, Producto } from "../tipos";

export function calcularTotal(pedido: Pedido): number {
  return pedido.productos.reduce((suma: number, p: Producto) => {
    return suma + p.precio * p.cantidad;
  }, 0);
}

export function aplicarDescuento(total: number, porcentaje: number): number {
  return total - (total * porcentaje) / 100;
}

Paso 3: Crea una utilidad de formato

Crea el archivo src/utilidades/formato.ts:

export function formatearPesos(cantidad: number): string {
  return "$" + cantidad.toLocaleString("es-MX", {
    minimumFractionDigits: 2,
    maximumFractionDigits: 2
  });
}

Paso 4: Escribe el punto de entrada

Crea el archivo src/index.ts:

import { Pedido } from "./tipos";
import { calcularTotal, aplicarDescuento } from "./servicios/productos";
import { formatearPesos } from "./utilidades/formato";

const pedido: Pedido = {
  id: "PED-001",
  cliente: "Ana García",
  productos: [
    { nombre: "Cafetera", precio: 1200, cantidad: 1 },
    { nombre: "Tazas (set)", precio: 350, cantidad: 2 },
    { nombre: "Molinillo", precio: 850, cantidad: 1 }
  ]
};

const total = calcularTotal(pedido);
const totalConDescuento = aplicarDescuento(total, 10);

console.log(`Cliente: ${pedido.cliente}`);
console.log(`Total sin descuento: ${formatearPesos(total)}`);
console.log(`Total con 10% de descuento: ${formatearPesos(totalConDescuento)}`);

Compilar y ejecutar

Desde la raíz del proyecto, ejecuta:

npm run build

Deberías ver la carpeta dist/ con los archivos JavaScript generados. Después ejecuta:

npm run start

La salida en consola será:

Cliente: Ana García
Total sin descuento: $2,750.00
Total con 10% de descuento: $2,475.00

Si ves esos resultados, tu proyecto TypeScript con Node.js funciona correctamente.

Errores comunes

Error 1: Olvidar instalar @types/node

Sin ese paquete, TypeScript no reconoce funciones como console.log o módulos como fs. El compilador lanza errores como Cannot find name 'console'. Solución: ejecuta npm install --save-dev @types/node.

Error 2: Ejecutar los archivos .ts directamente con Node

Node no entiende TypeScript. Si ejecutas node src/index.ts, obtendrás un error de sintaxis. Siempre compila primero con npm run build y luego ejecuta el archivo dentro de dist/.

Error 3: Rutas de importación incorrectas después de compilar

Cuando configuras rootDir y outDir, TypeScript replica la estructura de carpetas de src/ dentro de dist/. Si cambias la estructura de carpetas sin actualizar el tsconfig.json, las rutas rompen. Revisa siempre que rootDir apunte a la carpeta correcta.

Error 4: No excluir dist/ en tsconfig.json

Si olvidas agregar "dist" en la opción exclude, TypeScript intenta compilar los archivos ya compilados. Eso genera errores confusos y archivos duplicados. Asegúrate de que exclude siempre incluya "node_modules" y "dist".

Lo que aprendiste en este curso

A lo largo de las nueve lecciones cubriste los fundamentos completos de TypeScript:

• Tipos básicos y anotaciones: string, number, boolean, array y cómo declararlos.
• Interfaces y tipos personalizados: cómo modelar datos del mundo real, como productos de Bimbo o FEMSA.
• Funciones tipadas: parámetros, valores de retorno y funciones opcionales.
• Clases y herencia: programación orientada a objetos con verificación de tipos.
• Genéricos: código reutilizable que funciona con cualquier tipo de dato.
• Enums y tipos literales: valores fijos que evitan errores de escritura.
• Módulos y organización: cómo dividir el código en archivos y carpetas.
• Proyecto real con Node.js: configuración completa lista para producción.

Próximos pasos recomendados

Ahora que dominas los fundamentos, estas son las rutas naturales para continuar:

Si quieres desarrollo web: Aprende React con TypeScript. Muchas empresas mexicanas como Kueski o Clip usan esta combinación para sus aplicaciones de usuario.

Si quieres desarrollo backend: Explora frameworks como Express o Fastify con TypeScript. Puedes construir APIs REST que consuman datos del SAT o se conecten al sistema del IMSS.

Si quieres mejorar tu salario: Los desarrolladores con TypeScript en México ganan entre $18,500 y $28,000 al mes en posiciones junior a semi-senior, según reportes de bolsas de trabajo como OCC Mundial y Computrabajo.

Práctica inmediata: Toma cualquier proyecto JavaScript que hayas hecho antes y conviértelo a TypeScript. Ese ejercicio consolida todo lo aprendido mejor que cualquier tutorial.