Node.js + TypeScript: Una integración nativa años en desarrollo

Bienvenidos a todos a JS Nation. Hoy, daré mi charla sobre la integración de NodeJS y TypeScript, algo que tomó muchos años pero finalmente ha llegado. Así que permítanme presentarme. Mi nombre es Marco Ippolito. Soy un ingeniero de seguridad senior en Herodevs y miembro del Comité de Dirección Técnica de NodeJS.

Así que comencemos con un poco de clase de historia. Entonces, en la época de los seres humanos, hubo un tiempo en que los humanos solían escribir código en JavaScript, y de alguna manera hoy hemos hecho la transición a TypeScript. Pero, ¿cómo sucedió esto y cómo era la Tierra hace algunos años? Así que este es el estado de JavaScript en 2016. Podemos ver que en ese momento, el panorama de los frameworks y lenguajes de JS era un poco diferente. Había lenguajes como M y ClojureScript y CoffeeScript. Y TypeScript nació unos años antes, en 2014, pero realmente no era tan popular como hoy en ese momento.

De hecho, podemos ver que solo el 39% de los encuestados mencionaron que habían oído hablar de TypeScript y les gustaría probarlo. Así que en ese momento, hace casi 10 años, era algo nuevo y no muy conocido. Pero si miramos hoy, esto es 2024, GitHub, los principales lenguajes de programación, podemos ver que TypeScript es el número tres y está en ascenso. Y también, según GitHub, también es el segundo lenguaje de programación de más rápido crecimiento. Bueno, después de Python debido a la IA. Pero TypeScript está en ascenso. Así que en Node.js, siempre hemos recibido muchos problemas y solicitudes, solicitudes de características sobre la integración de TypeScript de forma nativa a lo largo de los años. Pero el problema con la integración de TypeScript de forma nativa en Node es que el más grande es que TypeScript y Node.js tienen diferentes garantías de estabilidad. Así que, por ejemplo, TypeScript no sigue Sambar y cada versión menor tiene cambios incompatibles. Y esto hace que sea difícil integrarlo dentro de Node.js. Tiene un seguimiento estricto de Sambar y tiene un ciclo de lanzamiento de tres años. Así que durante esos tres años, no podemos hacer cambios incompatibles. Y por lo tanto, no podemos actualizar las versiones de TypeScript. Otro gran problema es que Node.js sufrió algunos problemas con la interoperabilidad de Common JS y ESM. Esos problemas se han solucionado en Node.20. Así que esto fue un problema en versiones anteriores. Otro problema es que TypeScript requiere mapas de origen y los mapas de origen son lentos y propensos a errores. Y es algo que realmente no quieres a menos que sea necesario.

Así que habilitar el source map globalmente no es una buena idea. Y finalmente, Node Champion. Esta fue una gran función para implementar y básicamente nadie quería hacer el trabajo. Pero el año pasado, tuve algo de tiempo libre. Así que abrí un PR para integrar TypeScript en Node.js. Este PR se implementó en julio de 2024. Y así creamos algo llamado TypeStripping, que es algo.

Es una forma de soportar TypeScript sin realmente soportar todo TypeScript en sí. Así que vamos a verlo. ¿Qué es TypeStripping? Así que imagina que tenemos este código TypeScript. Hay una interfaz. Hay algunos tipos alrededor. Así que imagina que tomamos un borrador y comenzamos a eliminar todos estos tipos. Así que simplemente los borramos. Y al final del día, el resultado final es una función, printLabel, que hace console.glob.

OK, así que básicamente ignoramos todo lo que es TypeScript y todo. La salida es un JavaScript válido porque se supone que TypeScript es un superconjunto de JavaScript. Pero esto tiene algunos problemas porque ahora necesitaremos SourceMap para mapear todo a su archivo TypeScript original. Pero podemos omitir SourceMap reemplazando la sintaxis eliminada con espacios en blanco. Así que si ponemos espacio en blanco aquí, la salida se ve así. Y esto no necesita SourceMaps porque las ubicaciones se preservan.

Entonces, ¿qué es TypeStripping? Es simplemente ejecutar archivos TypeScript eliminando la sintaxis de TypeScript. Esto no realiza verificación de tipos. El problema con la verificación de tipos es que solo el paquete npm de TypeScript en sí puede hacer la verificación de tipos. Y como no podemos integrarlo, no podemos realizar la verificación de tipos. Pero como tienes un servidor de lenguaje TypeScript en tu IDE, estás bien. Porque a medida que desarrollas, puedes ver errores de tipo.

Y también puedes integrar la verificación de tipos en tu CI ya que no es algo que quieras hacer constantemente. No requiere tsconfig porque ignoramos todo lo relacionado con TypeScript. Así que simplemente ejecutamos JavaScript más tipos. Y eliminamos esos tipos en línea. Así que todo lo que se puede eliminar es compatible. Verás que no todo es un tipo en línea porque TypeScript contiene alguna sintaxis que no son solo tipos, sino que afecta el comportamiento en tiempo de ejecución como enums.

Pero hablaremos de eso más tarde. No requiere SourceMaps. Así que esto es una gran ventaja para el rendimiento y la capacidad de depuración. Y es estable a través de las versiones de TypeScript porque TypeStripping solo se romperá donde se introduzca nueva sintaxis. Pero la nueva sintaxis se introduce solo en cambios importantes.

Así que podemos alinear nuestros calendarios de lanzamiento con TypeScript. El TypeStripping se realiza mediante una biblioteca integrada dentro de NodeCore llamada Amaro. Creé esta biblioteca inspirada por un nombre de, significa amargo en italiano debido a lo difícil que fue esta integración y tomó tantos años. Utiliza SWC bajo el capó. Así que es algo muy conocido dentro del ecosistema. Y así aterrizamos este soporte experimental en Node 22.

Ya puedes usar el soporte experimental de TypeScript con la bandera –experimental-typescript-support. Si estás usando una versión antigua. Luego también hicimos esta bandera implícita para que ya no necesites pasar tipos de script experimentales. Así que puedes simplemente ejecutar node-file.ts y ejecutarás archivos TypeScript. En ese momento, la característica emitía una advertencia experimental. Pero ahora la advertencia experimental ha desaparecido.

Así que hay algunas limitaciones. La primera es que solo se admiten las características de TypeScript que se pueden borrar. Hay algunas características en TypeScript que no se pueden borrar. El mayor ejemplo son los enums y los namespaces que exportan algún valor. Por ejemplo, este namespace aquí está exportando una función. Y tenemos un enum aquí. Así que cuando intentas transpilar TypeScript, esta característica de TypeScript, la salida se ve así. Así es como se ve un enum en JavaScript.

Como puedes ver, estas características realmente no se pueden borrar. Necesitan ser transpiladas a código JavaScript. Y no queremos realizar generación de código. Así que simplemente no soportamos esta característica. Además, TypeScript se ha alineado con el comportamiento de Node. Así que lanzaron una nueva bandera llamada Erasable Syntax Only. Así que cada vez que estés usando enums, namespaces, y todas estas características que requieren transformación, recibirás un error. Así que puedes asegurarte de que la sintaxis de TypeScript coincida con la soportada por Node.js. En Node 23.8, comenzamos a soportar namespaces que exportan sintaxis borrable, como tipos. Así que puedes usar namespaces. También proporcionamos una bandera para soportar esas características que requieren transformación. Se llama ExperimentalTransformTypes, pero requiere que los source maps estén habilitados.

Otra limitación es que no realizamos down leveling. Así que, por ejemplo, antes de Node 24, la palabra clave using necesitaba ser transpilada a JavaScript porque no era soportada por el motor de JavaScript en sí. Otra característica común son los decoradores. No los soportamos porque requieren polyfill. Y estamos esperando que estas características lleguen al lenguaje en 2.8 oficialmente. Esto es algo extraño para los desarrolladores de TypeScript, pero realmente tuvo sentido durante muchos años. Siempre que importes un archivo TypeScript, necesitas usar la extensión TypeScript. Puedes hacer esto pasando esta bandera a TypeScript, permitiendo importar extensiones TS. En este ejemplo, puedes ver que estamos importando foo desde foo.ts. Pero si intentas compilar, si intentas TypeScript, lanzará un error porque esta bandera es solo con no emit. Así que no puedes transpilar cuando usas esta bandera. Así que TypeScript permite la extensión TS, pero solo para verificación de tipos y no para transpilación. Esto fue cierto hasta TypeScript 5.7 donde se creó una nueva bandera. Se llama RevisedRelativeImportExtensions. Esto te permite transpilar importaciones con la extensión .ts a JavaScript.

Esto tiene más sentido porque en tiempo de ejecución es un archivo TypeScript, pero cuando se transpila, se convierte en un archivo JavaScript. Así que durante la transpilación, la salida contendrá la extensión correcta. Otra limitación es que siempre que importes un tipo, necesitas usar la palabra clave type.

En este ejemplo, el correcto es el de arriba donde estás importando type 1 y type 2 y pasas la palabra clave type. De lo contrario, Node pensará que esa es una sintaxis que no se puede borrar. Así que mantendrá la importación, pero en el otro archivo, en el archivo de exportación, borrará la exportación porque es, por ejemplo, una interfaz o un tipo. Así que habrá un error en tiempo de ejecución porque TypeScript no podrá encontrar la variable exportada. Así que si usas la palabra clave type, funcionará.

Finalmente, no permitimos ejecutar TypeScript en módulos de Node. La razón es que permitir TypeScript en módulos de Node sería un gran cambio para el ecosistema. Y rompería muchas aplicaciones que no dependen de TypeScript, que no soportan TypeScript, además de hacer que tu IDE sea muy lento. Así que por ahora, no hay TypeScript en módulos de Node. Y si intentas hacerlo, verás que se lanza un error.

Así que en este caso, estoy intentando ejecutar index.ts dentro de módulos de Node. Recibí este error. Sí, porque esto es algo que podría cambiar en el futuro. Pero por ahora, hay demasiados problemas como incompatibilidades e IDEs. Así que queremos prevenirlo. Este es el ts.config que puedes usar para ejecutar TypeScript dentro de Node. Esto es solo para TypeScript. Node no leerá el ts.config. Lo ignorará. Así que esto es solo para tu IDE y cuando realices la verificación de tipos. Esto es algo interesante. También añadimos la sintaxis de TypeScript en eval, para que puedas evaluar la sintaxis de TypeScript. Esto es bastante complicado de hacer. Así que, por ejemplo, este es un string de TypeScript ESM.

Así que cuando intentamos evaluar, hacemos muchos pasos. Primero, intentamos como módulo común JS. Si no es un módulo común JS, intentamos de nuevo como un módulo ESM. Si no es un módulo ESM, entonces intentamos de nuevo eliminar tipos en línea. Así que eliminamos los tipos e intentamos de nuevo. Esto es lo que parece la cadena después de eliminar los tipos. Mira, hay un hueco en el medio. Después de esto, intentamos de nuevo ejecutarlo como común JS. Si eso falla de nuevo, intentamos de nuevo ejecutarlo como un módulo ESM. Y este es un módulo ESM, así que funciona. Pero puedes omitir toda esta detección elegante con dash dash input dash type. Y pasas el módulo TypeScript a común JS TypeScript. Esto lo hace mucho, mucho más rápido.

Finalmente, veamos esta cadena. Esto parece una cadena TypeScript fetch algo. Pero si intentamos ejecutarlo en Node, la salida es false. Esto es bastante extraño. Porque esperamos realizar fetch y la salida es false. Entonces, ¿qué está pasando? Intenté lo mismo en el navegador y funciona. Y la salida es false, pero los navegadores no entienden TypeScript. Entonces, ¿qué está pasando? La cuestión es que esto es un JavaScript válido. Esto es JavaScript, no TypeScript. Bueno, puedes decir que también es TypeScript, pero es JavaScript. Así que en JavaScript, parece algo así. Tenemos una función global. Y la función es menor que un objeto global, que es mayor que una cadena. Y esta salida es false. Pero si intentamos ejecutar esto dentro del TS playground, la salida es un fetch. Y si intentamos ejecutar esto como TypeScript en Node, la salida es también una respuesta de este example.com. Así que como puedes ver, hay código que es ambiguo y tiene un comportamiento de ejecución diferente como JavaScript y como TypeScript.

Así que por defecto lo ejecutaremos como JavaScript. Pero si eres explícito y pasas el dash dash input type, puedes ejecutarlo como TypeScript. Entonces, ¿cuáles son los siguientes pasos? El siguiente paso es corregir errores. Desconectar en 22. De hecho, esto sucedió. Ahora esto está disponible en Node 22, que es el LTS activo. Así que puedes usar TypeScript en Node 22.

Y finalmente, hacerlo estable. Creo que se volverá estable a finales de noviembre de 2025. Así que con suerte aterrizará primero en Node 25 y luego se retroportará a todas esas líneas de lanzamiento. También puedes ejecutar type stripping en el navegador con ES model shims. Esto es genial. Así que puedes ejecutar TypeScript en el navegador.

Hicimos Amaro, que es el analizador de TypeScript, estable. Así que en preparación para el cambio de estabilidad en Node. También eliminamos la advertencia experimental. Así que no verás una advertencia experimental al ejecutarlo. Y también lo retroporté, como dije, a Node 22. Así que esto finalmente sucedió. Así que por favor pruébalo.

Si quieres involucrarte en todas las conversaciones sobre type stripping y soporte de TypeScript en Node, puedes usar el repositorio de Node.js TypeScript. Tenemos reuniones cada dos semanas con el equipo de TypeScript. Así que los comentarios siempre son bienvenidos. Y eso fue todo. Gracias por escuchar.