Migración y Tipado de Código Legacy de JavaScript a TypeScript: Guía Paso a Paso

🚀 Introducción a la Migración Progresiva de JavaScript a TypeScript

Migrar una aplicación grande de JavaScript a TypeScript puede parecer una tarea titánica al principio. Muchas organizaciones y desarrolladores se enfrentan al dilema de tener que reescribir todo el código base de golpe, lo cual es arriesgado, costoso y propenso a errores catastróficos en producción. Afortunadamente, TypeScript fue diseñado desde su concepción para permitir una adopción gradual.

En este tutorial exhaustivo, aprenderás cómo transformar un proyecto JavaScript legacy en un sistema fuertemente tipado utilizando estrategias probadas en entornos de producción. Veremos desde la configuración inicial del compilador hasta el manejo de librerías de terceros sin tipos y la refactorización paso a paso.

🛠️ Paso 1: Configuración Inicial y Estrategia del Archivo tsconfig.json

El primer paso para iniciar la migración es instalar TypeScript en tu proyecto legacy y configurar el archivo tsconfig.json. La clave para no romper el código existente durante las primeras fases es utilizar banderas flexibles que permitan a JavaScript coexistir pacíficamente con TypeScript.

Ejecuta el siguiente comando para instalar TypeScript en tu proyecto:

npm install --save-dev typescript

A continuación, genera tu archivo de configuración inicial ejecutando:

npx tsc --init

Para una fase inicial de migración, recomendamos un archivo tsconfig.json optimizado para la coexistencia. Modifica tu configuración para incluir las siguientes opciones:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "commonjs",
    "allowJs": true,
    "checkJs": false,
    "noEmit": true,
    "strict": false,
    "esModuleInterop": true,
    "skipLibCheck": true,
    "forceConsistentCasingInFileNames": true
  },
  "include": ["src/**/*"]
}

Explicación de las banderas clave:

• allowJs: true: Permite que el compilador procese archivos .js y .jsx, permitiendo que coexistan con los nuevos archivos .ts y .tsx.
• checkJs: false: Evita que TypeScript reporte errores de tipo masivos en tus archivos JavaScript originales antes de que estés listo para revisarlos.
• noEmit: true: Útil al principio si tu empaquetador actual (como Webpack o Babel) ya se encarga de compilar el código. TypeScript solo funcionará como validador estático.
• strict: false: Desactiva temporalmente las reglas estrictas para evitar una avalancha de errores de tipo en funciones heredadas.

📋 Paso 2: Uso de JSDoc como Puente de Transición

Si tu proyecto es masivo y no puedes permitirte renombrar cientos de archivos .js a .ts de inmediato, puedes aprovechar JSDoc para tipar tu código JavaScript actual sin cambiar la extensión de los archivos. El compilador de TypeScript puede leer comentarios JSDoc para inferir y validar tipos.

Considera esta función tradicional en JavaScript:

// utils.js
function calcularTotal(precio, impuesto, descuento) {
    let subtotal = precio + (precio * impuesto);
    return subtotal - descuento;
}

Puedes enriquecerla con JSDoc para que TypeScript comience a validarla:

// utils.js
/**
 * Calcula el total a pagar aplicando impuestos y descuentos.
 * @param {number} precio - El precio base del producto.
 * @param {number} impuesto - El porcentaje de impuesto (ej. 0.16).
 * @param {number} descuento - El valor monetario a descontar.
 * @returns {number} El precio final calculado.
 */
function calcularTotal(precio, impuesto, descuento) {
    let subtotal = precio + (precio * impuesto);
    return subtotal - descuento;
}

🔄 Paso 3: Renombrado de Archivos y Resolución de Tipos Implícitos (any implícito)

Una vez que te sientas cómodo con la configuración básica, el siguiente hito en la línea de tiempo de la migración es empezar a renombrar los archivos de .js a .ts (o .tsx si usas React).

Al renombrar tu primer archivo a .ts, es muy probable que te encuentres con el infame error de tipo implícito any:

// usuario.ts
function obtenerNombreCompleto(usuario) {
    // Error: Parameter 'usuario' implicitly has an 'any' type.
    return usuario.nombre + ' ' + usuario.apellido;
}

Solución al tipado de parámetros:

Para solucionar esto, debes crear interfaces o tipos explícitos para tus estructuras de datos:

// usuario.ts
interface UsuarioLegacy {
    nombre: string;
    apellido: string;
    edad?: number;
}

function obtenerNombreCompleto(usuario: UsuarioLegacy): string {
    return `${usuario.nombre} ${usuario.apellido}`;
}

📦 Paso 4: Manejo de Librerías de Terceros sin Tipos

Uno de los mayores obstáculos al migrar código legacy es el uso de librerías de JavaScript antiguo que no cuentan con definiciones de tipos oficiales. Cuando importas una librería de este tipo, TypeScript arrojará un error indicando que no encuentra el módulo.

Estrategias para lidiar con librerías externas:

1. Buscar tipos en DefinitelyTyped: Siempre verifica si existe el paquete @types/nombre-de-libreria en npm.
2. Crear declaraciones de módulos manuales: Si la librería no tiene tipos, puedes declarar un archivo de ambiente personalizado.

Crea un archivo llamado declarations.d.ts en la raíz de tu carpeta de tipos:

// declarations.d.ts
declare module 'libreria-legacy-custom' {
    export function iniciarPlugin(opciones: Record<string, any>): void;
    export const version: string;
}

Esto le dice a TypeScript que confíe en que la librería existe y expone esas firmas específicas, permitiéndote continuar con la migración sin bloquearte por dependencias externas desactualizadas.

🧗 Paso 5: Incrementando el Nivel de Rigor (Strict Mode)

El paso final y definitivo en la migración de tu proyecto es activar progresivamente las opciones estrictas de TypeScript en el archivo tsconfig.json. No lo hagas todo de golpe; sigue este orden recomendado:

❓ Preguntas Frecuentes sobre Migración a TypeScript

🏁 Conclusión

Migrar una aplicación de JavaScript a TypeScript no tiene por qué ser un proceso doloroso ni requerir una reescritura masiva desde cero. Siguiendo un enfoque metódico —comenzando con la configuración flexible de allowJs, utilizando JSDoc como puente, renombrando archivos por fases y endureciendo las reglas del compilador de forma paulatina— transformarás tu código legacy en una aplicación moderna, mantenible y altamente segura.

Recuerda que la meta no es lograr una compilación perfecta el primer día, sino mejorar continuamente la calidad de tu base de código iteración tras iteración.