Migrar de JavaScript a TypeScript paso a paso sin romper el proyecto

Migrar un proyecto JavaScript a TypeScript no tiene por qué hacerse de golpe ni parar el desarrollo. TypeScript está diseñado para una adopción incremental: puedes empezar con un solo fichero, avanzar a tu ritmo y activar las comprobaciones más estrictas cuando el equipo esté preparado. Esta guía cubre el proceso completo con las opciones de tsconfig que lo hacen posible.

El punto de partida: allowJs y checkJs

La forma más suave de empezar es activar allowJs, que permite que TypeScript incluya ficheros .js en la compilación sin obligarte a convertirlos:

// tsconfig.json inicial
{
  "compilerOptions": {
    "allowJs": true,
    "checkJs": false,      // no comprueba los .js todavía
    "outDir": "dist",
    "strict": false,       // empezaremos sin strict
    "target": "ES2020",
    "module": "CommonJS",
    "esModuleInterop": true,
    "skipLibCheck": true
  },
  "include": ["src"]
}

Con esta configuración, TypeScript procesa tus ficheros .js junto a los .ts pero sin añadir errores en los primeros. Puedes migrar un fichero a la vez.

Renombrado progresivo de ficheros

El paso más visible de la migración es renombrar .js a .ts. Hazlo módulo a módulo, empezando por los que tienen menos dependencias (utilidades, helpers, tipos de datos). Al renombrar un fichero, TypeScript empieza a comprobar sus tipos y mostrará errores que conviene corregir antes de continuar:

• Empieza por los ficheros de utilidades sin dependencias.
• Continúa con los modelos de datos y tipos.
• Avanza hacia los servicios y controladores.
• Deja para el final los puntos de entrada y ficheros con muchas dependencias.

Gestión de librerías sin tipos

Durante la migración encontrarás librerías de terceros sin ficheros de declaración. Tienes tres opciones:

// Opción 1: instalar los tipos de DefinitelyTyped
npm install --save-dev @types/nombre-libreria

// Opción 2: declaración mínima en un .d.ts propio (si no hay @types)
// @types/libreria-sin-tipos/index.d.ts
declare module "libreria-sin-tipos" {
  const valor: unknown;
  export default valor;
}

// Opción 3: añadir al tsconfig temporalmente (con precaución)
// "noImplicitAny": false  ? permite any implícito mientras migras

Activar strict de forma gradual

Activar "strict": true en un proyecto grande puede generar cientos de errores. La estrategia recomendada es activar las opciones de strict de una en una:

{
  "compilerOptions": {
    // Primera ronda: activar checkJs para los .js que quedan
    "checkJs": true,

    // Segunda ronda: añadir nullChecks
    "strictNullChecks": true,

    // Tercera ronda: eliminar any implícitos
    "noImplicitAny": true,

    // Cuarta ronda: el resto de strict
    "strict": true
  }
}

Herramientas que aceleran la migración

Varias herramientas automatizan parte del trabajo pesado:

• ts-migrate (de Airbnb): convierte ficheros JS a TS añadiendo anotaciones any donde no puede inferir. El resultado no es perfecto pero es un buen punto de partida.
• TypeStat: analiza el código e infiere tipos más precisos que any, ahorrando trabajo manual.
• JSDoc: si tu código tiene comentarios JSDoc, TypeScript los lee y usa para inferir tipos incluso en ficheros .js con checkJs: true.

Errores comunes durante la migración

El error más frecuente es intentar tener tipos perfectos desde el principio. Es mejor tener any en algunos sitios y un proyecto que compila que tipos perfectos en el 30% del código y un build roto. Marca los any temporales con un comentario // TODO: tipar para localizarlos fácilmente.

El segundo error es no activar strict desde el principio en los ficheros nuevos. Cada fichero .ts nuevo debería tener tipos completos. La deuda técnica de tipos incompletos en código nuevo crece más rápido que en el código migrado, porque el código nuevo sigue evolucionando mientras el viejo tiende a estabilizarse.

Imagen: Pexels / Mathews Jumba