Cómo incluir archivos JavaScript en un proyecto TypeScript

En los proyectos TypeScript algunas veces puede ser necesario integrar módulos escritos en JavaScript. Aunque traducir una función de JavaScript a TypeScript suele ser fácil, si el módulo es complejo puedes ser más rápido integrarlo directamente. En este caso, incluir simplemente incluir archivos .js en un proyecto TypeScript no llega para aprovechar las características avanzadas del lenguaje, incluso para que compile el proyecto. En esta entrada, se verá cómo incluir archivos JavaScript en un proyecto TypeScript, cómo crear archivos de definición de tipos (.d.ts) para aprovechar la tipificación estática de TypeScript en los módulos JavaScript, y cómo configurar correctamente el archivo tsconfig.json para que los archivos .js se copien junto con los archivos .ts.

Configurar el proyecto TypeScript para incluir archivos JavaScript

En primer lugar, para poder incluir archivos JavaScript en un proyecto TypeScript, es necesario agregar las opciones adecuadas en el archivo de configuración tsconfig.json. Se debe indicar al compilador que se van a usar archivos JavaScript en el proyecto. Para lo que se deben agregar las siguientes opciones.

{
  "compilerOptions": {
   ...
    "allowJs": true,           // Permite que TypeScript procese archivos JavaScript
    "checkJs": false,          // No verifica los archivos JS para errores de tipos
  ...
  },
  "include": [
    "src/**/*.ts",
    "src/**/*.js"              // Incluye archivos JS en la compilación
  ]
}

En donde las nuevas opciones representan:

En Analytics Lane

Nuevo simulador FIRE en el laboratorio de aplicaciones de Analytics Lane

• allowJs: true: Esta opción permite que el compilador TypeScript maneje archivos .js. Es crucial para que los archivos JavaScript se copien o compilen.
• checkJs: false: Evita que TypeScript verifique los tipos en los archivos .js, lo que te permite seguir trabajando sin que TypeScript marque errores en el código JavaScript.
• include: Esta opción especifica qué archivos deben ser incluidos en la compilación. Es necesario incluir tanto los archivos .ts como .js.

Crear archivos de definición de tipos (.d.ts) para las funciones JavaScript

Una vez que se ha configurado el proyecto para que el compilador de TypeScript puede emplear los archivos JavaScript. Evitando además que valide los tipos en estos para evitar errores. El siguiente paso es crear los archivos con las definiciones de tipos (.d.ts) en los que se definen las funciones y tipos de datos que se usan en el código JavaScript. Con lo que el compilador de TypeScript puede aprovechar los beneficios de la tipificación estática para validar que las funciones son usadas de forma adecuada.

¿Qué es un archivo .d.ts?

Un archivo .d.ts contiene únicamente declaraciones de tipos. No incluye la implementación de ninguna función o clase, sino que se usa para indicarle a TypeScript qué tipos existen en el módulo JavaScript.

Ejemplo de Archivo .d.ts

Supongamos que se tiene el siguiente archivo JavaScript math.js:

// math.js
function add(a, b) {
  return a + b;
}

function subtract(a, b) {
  return a - b;
}

module.exports = { add, subtract };

Un archivo que contiene dos funciones add() y subtract(). Para crear su archivo de definición de tipos, se debe crear un archivo llamado math.d.ts en el mismo directorio en que se encuentra math.js. Este archivo debe contener la definición de las funciones indicado los tipos de los parámetros y el tipo de dato que devuelve, para este ejemplo el archivo puede contener las siguientes líneas:

// math.d.ts
declare module 'math' {
  export function add(a: number, b: number): number;
  export function subtract(a: number, b: number): number;
}

El archivo math.d.ts le dice a TypeScript que el módulo math.js contiene dos funciones (add y subtract), que ambas aceptan dos parámetros numéricos y devuelven un número.

Importar y usar funciones JavaScript en TypeScript

Una vez definido el archivo de tipos, ya se pueden usar las funciones JavaScript dentro del proyecto TypeScript. Obteniendo las ventajas del tipado estático:

import { add, subtract } from 'math';

const sum: number = add(5, 10);
const difference: number = subtract(10, 5);

console.log(`Suma: ${sum}, Diferencia: ${difference}`);

Gracias al archivo de tipos .d.ts, TypeScript puede verificar que se usan las funciones de forma correcta. Produciendo el compilador advertencias si se hace algo mal, cómo pasar argumentos no válidos.

Compilar y copiar los archivos JavaScript

Una vez configurado el archivo tsconfig.json, se puede ejecutar el compilador de TypeScript para compilar el proyecto copiando también los archivos JavaScript en la carpeta de salida:

npx tsc

Con la configuración indicada anteriormente, este comando procesa tanto los archivos .ts como los .js, copiándolos a la carpeta dist.

Conclusiones

Integrar archivos JavaScript en un proyecto TypeScript es un proceso sencillo. Se debe configurar el archivo tsconfig.json para usar los archivos .js y crear los archivos de definición de tipos. Así, el compilador de TypeScript sabrá cómo usar las funciones JavaScript y las incluirá en la compilación.

Nota: La imagen de este artículo fue generada utilizando un modelo de inteligencia artificial.