~/articulo tree
Adoptar TypeScript en un proyecto ya en marcha es una de las decisiones técnicas más frecuentes (y más subestimadas) que toman los equipos de producto.
La promesa es clara: menos bugs en runtime, mejor autocompletado, código más legible. La realidad incluye migraciones dolorosas, configuraciones que nadie entiende y debates interminables sobre tipos genéricos.
Hemos migrado varios proyectos de JavaScript a TypeScript en producción. Esto es lo que nadie te dice antes de empezar.
La migración gradual: la única forma sensata
Intentar migrar todo el proyecto de una vez es una receta para el desastre. La estrategia correcta es la migración gradual: empezar con allowJs: true y strict: false, e ir aumentando la rigurosidad archivo por archivo.
- Configura tsconfig con allowJs: true, permite mezclar .js y .ts en el mismo proyecto
- Empieza por los módulos más compartidos: utils, tipos globales, helpers
- Activa strict: true solo en los archivos ya migrados usando // @ts-strict
- Nunca uses any como solución permanente: documéntalo como deuda técnica
Errores que cometemos todos al principio
El más común: tipar todo con any para que «el compilador se calle». Funciona a corto plazo y destruye el valor de TypeScript a largo plazo.
- Usar as unknown as T para forzar tipos: señal de que el diseño del tipo está mal
- No tipar las respuestas de APIs externas: origen del 80% de los bugs en runtime
- Genéricos excesivamente complejos que nadie del equipo puede leer 3 meses después
- tsconfig muy permisivo que no aprovecha las ventajas de TypeScript
Patrones que sí funcionan en producción
| Patrón | Cuándo usarlo | Beneficio |
|---|---|---|
| Zod para validación de runtime | Datos de APIs externas y formularios | Sincroniza tipos estáticos con validación real |
| Discriminated unions | Modelar estados finitos (loading/error) | Elimina estados imposibles del sistema |
| Template literal types | Strings con formato conocido (rutas, IDs) | Previene errores de tipeo en strings críticos |
| Satisfies operator | Configuraciones complejas con inferencia | Valida el tipo sin perder la inferencia automática |
¿Vale la pena el esfuerzo?
Después de migrar proyectos grandes, la respuesta es sí: pero solo si el equipo se compromete a usar TypeScript correctamente, no solo a satisfacer al compilador.
Los equipos que lo hacen bien reportan una reducción significativa de bugs en producción, onboarding más rápido para nuevos desarrolladores y mayor confianza al hacer refactors grandes.
Conclusión
TypeScript es una inversión, no un interruptor. El valor real aparece semanas después de la migración, cuando el equipo empieza a refactorizar con confianza y los bugs de runtime se vuelven una rareza.
~/siguiente-paso$ montreach contact
Cuéntanos qué necesitas y te proponemos un primer paso concreto.