Conceptos básicos de TypeScript en Node

8 ejemplos para empezar con TypeScript en Node: 6 básicos y 2 intermedios.

Prerrequisitos

• Node.js 24.18.0, TypeScript 5.6+, npm install -D typescript tsx @types/node.
• "type": "module" en package.json para los ejemplos de ESM a continuación.

Ejemplos básicos

1. tsconfig mínimo para Node 24 ESM

NodeNext alinea TypeScript con el resolvedor de módulos de Node.

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "moduleResolution": "NodeNext",
    "strict": true,
    "skipLibCheck": true,
    "outDir": "dist",
    "rootDir": "src"
  },
  "include": ["src"]
}

• strict habilita strictNullChecks, noImplicitAny y banderas relacionadas juntas.
• skipLibCheck acelera las compilaciones; aún así verifica los tipos de tu src.
• outDir/rootDir mantienen dist/ reflejando src/.

Relacionado: tsx vs tsc vs ts-node - pipelines de desarrollo vs producción

2. process.env tipado (predeterminado inseguro)

Los valores de process.env son string | undefined; refínalos antes de usarlos.

const port = Number(process.env.PORT ?? 3000);
if (Number.isNaN(port)) throw new Error('Invalid PORT');

• Las variables de entorno siempre son cadenas cuando están presentes.
• ?? maneja undefined; la cadena vacía necesita un manejo explícito.
• Valida las variables requeridas al inicio; consulta el ejemplo de Zod en Zod en los límites.

3. Importar módulos nativos con tipos

@types/node viene con tipados de calidad DefinitelyTyped para las API de Node 24.

import { readFile } from 'node:fs/promises';
import type { Stats } from 'node:fs';
 
const stat: Stats = await readFile('package.json').then(() => import('node:fs')).then(fs => fs.promises.stat('package.json'));

• Usa import type para importaciones solo de tipos con verbatimModuleSyntax.
• La versión de @types/node debe coincidir con tu versión principal de Node (npm i -D @types/node@24).
• Prefiere el prefijo node: en el código de la aplicación.

4. Rutas de importación ESM con extensión .js

TypeScript importa .js porque la emisión mantiene los especificadores sin cambios.

// src/user.ts
export interface User { id: string; name: string }

// src/main.ts
import { type User } from './user.js';

• Esto parece extraño en los archivos .ts, pero coincide con la resolución en tiempo de ejecución de Node ESM.
• moduleResolution: NodeNext impone este patrón.
• Los empaquetadores pueden reescribir extensiones; las aplicaciones Node sin empaquetar no pueden.

Relacionado: Módulos ES (importación) - reglas de ESM

5. Tipo de retorno del manejador asíncrono

Los manejadores de Express/Fastify deben devolver void o Promise<void> explícitamente.

import type { Request, Response } from 'express';
 
export async function getHealth(_req: Request, res: Response): Promise<void> {
  res.json({ status: 'ok' });
}

• Los manejadores asíncronos devuelven Promesas; asegúrate de que los errores se propaguen al middleware de errores.
• Usa tipos específicos del framework para la aumentación de solicitudes; consulta Tipado de manejadores de Express/Fastify.
• Evita any en req y res; define genéricos para body y params.

6. node:test con TypeScript

Pruebas nativas con tipos; no se necesita Jest para las pruebas unitarias.

import { test } from 'node:test';
import assert from 'node:assert/strict';
 
function slugify(input: string): string {
  return input.toLowerCase().replace(/\s+/g, '-');
}
 
test('slugify', () => {
  assert.equal(slugify('Hello World'), 'hello-world');
});

node --import tsx --test src/**/*.test.ts

• Coloca *.test.ts junto al código fuente o debajo de src/__tests__.
• assert/strict lanza un error en caso de fallo con diferencias claras.
• CI puede ejecutar dist/**/*.test.js compilado después de tsc para paridad.

Ejemplos intermedios

7. Refinamiento estricto de nulos

strictNullChecks fuerza el manejo de null y undefined.

function findUser(id: string, users: Map<string, { name: string }>): string {
  const user = users.get(id);
  if (!user) throw new Error(`User ${id} not found`);
  return user.name;
}

• El encadenamiento opcional user?.name devuelve string | undefined; aún así refina para la lógica de negocio.
• Evita la aserción de no nulo ! excepto en pruebas o después de guardas explícitas.
• Las capas de base de datos que devuelven null deben mapearse a tipos Result o excepciones en los límites.

Relacionado: Zod en los límites - validación en tiempo de ejecución

8. Paquete de tipos compartidos (Monorepo)

Publica tipos DTO sin componentes internos del servidor.

// packages/types/src/user.ts
export interface UserDto {
  id: string;
  displayName: string;
}

// apps/api/src/handlers/user.ts
import type { UserDto } from '@acme/types/user';
 
export function toDto(user: { id: string; name: string }): UserDto {
  return { id: user.id, displayName: user.name };
}

• Exporta módulos solo de tipos; no hay secretos del servidor en el paquete compartido.
• Usa exports en @acme/types/package.json para subrutas.
• Consulta Compartir tipos con el frontend para ver patrones completos de monorepo.

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