Mejores prácticas de TypeScript en Node

TypeScript rinde frutos cuando las comprobaciones estrictas en tiempo de compilación se encuentran con la validación en tiempo de ejecución en los límites, no cuando any se filtra a través de los resultados del ORM y los cuerpos de las solicitudes.

Cómo usar esta lista

• Aplícala a cada nuevo servicio y a cada módulo migrado que abandone allowJs.
• Bloquea las PR que añadan any o @ts-ignore sin justificación en el ticket.
• Combínala con tsc --noEmit y pruebas en CI: los tipos sin pruebas siguen enviando errores.
• Revísala al actualizar las versiones principales de TypeScript para nuevas banderas estrictas.

A - Configuración del compilador y del proyecto

• Habilita strict: true para todos los proyectos nuevos. Añade banderas más estrictas (noUncheckedIndexedAccess) cuando el equipo esté listo.
• Usa module / moduleResolution: NodeNext en Node 24 ESM. Coincide con el resolvedor en tiempo de ejecución.
• Ejecuta tsc --noEmit en CI en cada PR. El desarrollo solo con tsx no realiza la comprobación de tipos.
• Emite dist/ para contenedores de producción. CMD ["node", "dist/main.js"] - sin tsx en la imagen de producción.
• Fija typescript y @types/node a versiones principales compatibles. Alinea @types/node con Node 24.

B - Límites y tiempo de ejecución

• Valida process.env con Zod al inicio. Falla antes de escuchar en un puerto.
• Analiza cuerpos HTTP, consultas y parámetros con esquemas. Nunca as Foo en req.body.
• Deriva tipos con z.infer - sin interfaces duplicadas. Una única fuente de verdad.
• Mapea explícitamente las entidades de la base de datos a DTOs. No exportes modelos ORM a los clientes.
• Trata las respuestas de SDK externos como unknown hasta que se analicen. Incluso de proveedores de confianza.

C - Estilo y seguridad del código

• Prefiere import type para importaciones solo de tipos. Habilita verbatimModuleSyntax en nuevos repositorios.
• Evita any - usa unknown + estrechamiento. ESLint @typescript-eslint/no-explicit-any como error.
• Limita las aserciones no nulas (!) a las pruebas. El código de producción usa guardas o Zod.
• Usa uniones discriminadas para tipos de resultado. { ok: true, value } | { ok: false, error }.
• No uses @ts-ignore - usa @ts-expect-error con ticket y fecha de eliminación.

D - Integración del framework

• Aumenta Request de Express solo para campos transversales. Genéricos por ruta para cuerpo/parámetros.
• Usa esquemas de Fastify o un proveedor de tipos Zod. Una fuente de validación para rutas de Fastify 5.
• Tipifica los manejadores asíncronos como Promise<void> de retorno. Asegúrate de que los errores lleguen a los hooks de error del framework.
• Comparte paquetes DTO - no internos del servidor - con el frontend. Patrón @acme/api-types.
• DTOs de NestJS: valida con pipes, no solo con decoradores. class-validator o Zod en el límite.

E - Migración y mantenimiento

• Ratchet: no hay nuevos archivos .js en directorios tipados. allowJs es temporal.
• Convierte las utilidades hoja antes que los archivos de ruta. La migración de abajo hacia arriba reduce la rotación del grafo.
• Añade tipos a las suites node:test temprano. Las pruebas bloquean el comportamiento durante el cambio de nombre de JS a TS.
• Revisa las notas de lanzamiento de TypeScript para nuevas opciones estrictas trimestralmente. Opta deliberadamente.
• Mantén el paquete de tipos compartidos libre de importaciones node:*. Seguro para los bundlers de React.

Preguntas frecuentes

Relacionado

• Zod en los límites - validación en tiempo de ejecución
• Conceptos básicos de TypeScript en Node - tsconfig inicial
• Tipado gradual en código existente - guía de migración
• Comprobación de tipos en CI - aplicación

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.