El compilador de TypeScript y el archivo tsconfig

Quiero compartir un resumen práctico del compilador de TypeScript. La herramienta tsc es la encargada de compilar nuestro código TypeScript, observar cambios en tiempo real, verificar tipos y mucho más.

El comando tsc acepta parámetros durante su ejecución y también puede leer la configuración directamente desde un archivo tsconfig.json.

En este post te voy a mostrar cómo trabajar con el compilador desde la terminal, cómo generar el archivo tsconfig.json y cuáles son las opciones más importantes para tu día a día.

Cómo usar el compilador tsc

El compilador tsc convierte el código TypeScript en JavaScript estándar. Para ver esto en acción, voy a crear un archivo app.ts con unas pocas líneas de TypeScript:

class App {
  name: string;
  constructor(name: string) {
    this.name = name;
  }
  congrats(): void {
    console.log(`Hello ${this.name}.`);
  }
}

Luego, ejecutamos tsc desde la terminal pasando el archivo app.ts:

tsc app.ts

El compilador toma nuestro código TypeScript y genera un archivo JavaScript listo para ejecutar:

"use strict";
var App = /** @class */ (function () {
    function App(name) {
        this.name = name;
    }
    App.prototype.congrats = function () {
        console.log("Hello " + this.name + ".");
    };
    return App;
}());

Cómo usar el modo watch

El siguiente paso sería modificar app.ts y volver a compilar. Sin embargo, ejecutar tsc a mano tras cada cambio no es una buena idea ni resulta práctico.

El compilador tsc puede observar cada cambio en app.ts si usamos el parámetro --watch (o -w). De esta forma, queda escuchando cualquier modificación en el archivo:

C:\Users\dany\Desktop\hello-typescript\app>tsc app.ts -w
[3:41:21 PM] Starting compilation in watch mode...
 
[3:41:23 PM] Found 0 errors. Watching for file changes.
 
[3:41:44 PM] File change detected. We were starting incremental compilation.
 
[3:41:44 PM] Found 0 errors. Watching for file changes.

El modo watch funciona muy bien para una prueba rápida o un archivo individual. Sin embargo, en proyectos más grandes donde necesitas compilar muchos archivos, usar la línea de comandos deja de ser una solución cómoda. Para resolver esto, recurrimos al archivo de configuración.

Cómo crear el archivo tsconfig.json

El compilador de TypeScript nos permite definir todas las opciones del proyecto dentro de un archivo de configuración llamado tsconfig.json.

Cuando tsc encuentra un tsconfig en el directorio, entiende que ese directorio corresponde a un proyecto TypeScript y lee las opciones configuradas, como el modo watch, la versión de JavaScript y más.

Podemos generar este archivo ejecutando el comando tsc --init, lo cual crea un tsconfig.json con la configuración por defecto:

C:\Users\dany\Desktop\hello-typescript\app>tsc --init
message TS6071: Successfully created a tsconfig.json file.

Ahora puedo volver a ejecutar tsc con la opción --watch, y el compilador procesará todos los archivos TypeScript del directorio.

Excluir e incluir archivos

El archivo tsconfig.json contiene muchas opciones para controlar la compilación de archivos y la calidad del código. Entre las más útiles para gestionar qué archivos procesar están:

exclude: Permite definir una lista de archivos o patrones que queremos excluir del proceso de compilación.

exclude : [ "somefile.ts", "**/legacy/*.ts"]

include: Ayuda a especificar qué archivos o patrones deben incluirse en la compilación. Por defecto toma todos los archivos del proyecto, pero resulta muy útil cuando necesitas compilar algún archivo fuera de la raíz habitual.

include : [ "somefile.ts", "**/legacy/*.ts"]

Opciones de compilación (compilerOptions)

El bloque compilationOptions reúne ajustes básicos muy útiles tanto para la generación de código como para la revisión de calidad. Aquí tienes las opciones que más utilizo:

target: Define la versión de JavaScript a la que TypeScript convertirá el código. Por defecto era ES3, pero puedes cambiarlo a ES6, ES2020 o ESNEXT.

El resultado cambia de forma drástica si compilas app.ts con las versiones es5 y ES2015.

El código generado con ES2015 es muy parecido al de app.ts, ya que ES2015 soporta la palabra clave class de forma nativa:

 use strict";
class App {
    constructor(name) {
        this.name = name;
    }
    congrats() {
        console.log(`Hello ${this.name}.`);
    }
}

En cambio, el código generado en es5 no incluye class ni constructor, porque es5 no reconocía esa sintaxis y recurre a prototipos:

"use strict";
var App = /** @class */ (function () {
    function App(name) {
        this.name = name;
    }
    App.prototype.congrats = function () {
        console.log("Hello " + this.name + ".");
    };
    return App;
}());

lib: Ayuda a indicar qué librerías del entorno se deben incluir en la compilación. Si no se especifica, incluye por defecto la librería del DOM, es6 y las definiciones más habituales.

sourceMap: Al configurarlo en true, el compilador genera mapas de origen (source maps) para el código TypeScript, lo que facilita depurar directamente en el navegador.

outDir: Permite enviar los archivos compilados a un directorio específico, como dist o build. La estructura de carpetas de nuestro proyecto se replica intacta en dicho directorio.

noEmitOnError: Por defecto, el compilador siempre genera los archivos .js. Si activas esta opción en true, el compilador no creará ningún archivo de salida si encuentra algún error en el código.

strict: Activa todas las comprobaciones estrictas de tipos por defecto, como la verificación de valores nulos y la inicialización estricta de propiedades. Es una opción clave para evitar errores comunes en tiempo de ejecución.

noUnusedLocals: Si lo defines en true, el compilador mostrará un error cuando existan variables locales o propiedades que no se estén utilizando.

noUnusedParameters: Al definirlo en true, el compilador marcará un error si una función recibe parámetros que no se usan en su implementación.

noImplicitReturns: Si se activa en true, el compilador reportará un error cuando no todas las rutas de código dentro de una función retornen un valor.

noFallthroughCasesInSwitch: Al configurarlo en true, el compilador mostrará un error si un caso dentro de una sentencia switch no cuenta con una cláusula break o return.

watch: Si se define en true, tsc compilará y observará cambios de forma automática, igual que ejecutar tsc -w.

Hay muchas más opciones disponibles para tsconfig.json. Puedes consultar la documentación completa en la página oficial de TypeScript.

Conclusión

Espero que este repaso te sirva como punto de partida para usar el compilador de TypeScript y configurar tu archivo tsconfig.json con opciones de calidad de código y modo estricto.

Si te gustó este post, compártelo con tu equipo o en tus redes sociales :).

Photo by Michael Dziedzic on Unsplash