Módulos: TypeScript

[Historial]

Versión	Cambios
v22.7.0	Se añadió la bandera --experimental-transform-types.

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.1 - Desarrollo activo

Habilitación

Hay dos maneras de habilitar la compatibilidad con TypeScript en tiempo de ejecución en Node.js:

Soporte completo de TypeScript

Para usar TypeScript con soporte completo para todas las funciones de TypeScript, incluyendo tsconfig.json, puedes usar un paquete de terceros. Estas instrucciones usan tsx como ejemplo, pero hay muchas otras bibliotecas similares disponibles.

Eliminación de tipos

Añadido en: v22.6.0

[Estable: 1 - Experimental]

Estable: 1 Estabilidad: 1.1 - Desarrollo activo

La bandera --experimental-strip-types permite a Node.js ejecutar archivos TypeScript. Por defecto, Node.js ejecutará solo los archivos que no contengan funciones de TypeScript que requieran transformación, como enums o espacios de nombres. Node.js reemplazará las anotaciones de tipo en línea con espacios en blanco, y no se realizará ninguna verificación de tipo. Para habilitar la transformación de tales funciones, usa la bandera --experimental-transform-types. Las funciones de TypeScript que dependen de la configuración dentro de tsconfig.json, como las rutas o la conversión de la sintaxis de JavaScript más reciente a estándares más antiguos, no son compatibles intencionalmente. Para obtener soporte completo de TypeScript, consulta Soporte completo de TypeScript.

La función de eliminación de tipos está diseñada para ser ligera. Al no admitir intencionalmente sintaxis que requieren generación de código JavaScript, y al reemplazar los tipos en línea con espacios en blanco, Node.js puede ejecutar código TypeScript sin necesidad de mapas de origen.

La eliminación de tipos funciona con la mayoría de las versiones de TypeScript, pero recomendamos la versión 5.7 o más reciente con la siguiente configuración de tsconfig.json:

{
  "compilerOptions": {
    "target": "esnext",
    "module": "nodenext",
    "allowImportingTsExtensions": true,
    "rewriteRelativeImportExtensions": true,
    "verbatimModuleSyntax": true
  }
}

Determinación del sistema de módulos

Node.js admite tanto la sintaxis de CommonJS como la de ES Modules en archivos TypeScript. Node.js no realizará la conversión de un sistema de módulos a otro; si quieres que tu código se ejecute como un módulo ES, debes usar la sintaxis import y export, y si quieres que tu código se ejecute como CommonJS, debes usar require y module.exports.

• Los archivos .ts tendrán su sistema de módulos determinado de la misma manera que los archivos .js. Para usar la sintaxis import y export, agrega "type": "module" al package.json padre más cercano.
• Los archivos .mts siempre se ejecutarán como módulos ES, similar a los archivos .mjs.
• Los archivos .cts siempre se ejecutarán como módulos CommonJS, similar a los archivos .cjs.
• Los archivos .tsx no son compatibles.

Como en los archivos JavaScript, las extensiones de archivo son obligatorias en las sentencias import y las expresiones import(): import './file.ts', no import './file'. Debido a la compatibilidad con versiones anteriores, las extensiones de archivo también son obligatorias en las llamadas require(): require('./file.ts'), no require('./file'), de forma similar a cómo la extensión .cjs es obligatoria en las llamadas require en archivos CommonJS.

La opción allowImportingTsExtensions de tsconfig.json permitirá al compilador TypeScript tsc verificar los archivos con especificadores import que incluyen la extensión .ts.

Características de TypeScript

Dado que Node.js solo está eliminando los tipos en línea, cualquier característica de TypeScript que implique reemplazar la sintaxis de TypeScript con una nueva sintaxis de JavaScript generará un error, a menos que se pase el indicador --experimental-transform-types.

Las características más destacadas que requieren transformación son:

• Enum
• namespaces
• legacy module
• propiedades de parámetros

Dado que los Decoradores son actualmente una propuesta de Etapa 3 de TC39 y pronto serán compatibles con el motor de JavaScript, no se transforman y generarán un error de análisis. Esta es una limitación temporal y se resolverá en el futuro.

Además, Node.js no lee los archivos tsconfig.json y no admite características que dependan de la configuración dentro de tsconfig.json, como las rutas o la conversión de sintaxis de JavaScript más nueva a estándares más antiguos.

Importación de tipos sin la palabra clave type

Debido a la naturaleza de la eliminación de tipos, la palabra clave type es necesaria para eliminar correctamente las importaciones de tipos. Sin la palabra clave type, Node.js tratará la importación como una importación de valor, lo que generará un error en tiempo de ejecución. La opción tsconfig verbatimModuleSyntax se puede utilizar para que coincida con este comportamiento.

Este ejemplo funcionará correctamente:

import type { Type1, Type2 } from './module.ts'
import { fn, type FnParams } from './fn.ts'

Esto generará un error en tiempo de ejecución:

import { Type1, Type2 } from './module.ts'
import { fn, FnParams } from './fn.ts'

Formas de entrada que no son archivos

El despojo de tipos puede habilitarse para --eval. El sistema de módulos se determinará mediante --input-type, como sucede con JavaScript.

La sintaxis de TypeScript no se admite en REPL, la entrada STDIN, --print, --check e inspect.

Mapas de origen

Dado que los tipos en línea se reemplazan con espacios en blanco, los mapas de origen son innecesarios para que los números de línea en los seguimientos de pila sean correctos; y Node.js no los genera. Cuando --experimental-transform-types está habilitado, los mapas de origen se habilitan de forma predeterminada.

Despojo de tipos en dependencias

Para disuadir a los autores de paquetes de publicar paquetes escritos en TypeScript, Node.js, de forma predeterminada, se negará a gestionar archivos de TypeScript dentro de las carpetas que se encuentran bajo una ruta node_modules.

Alias de rutas

tsconfig "paths" no se transformarán y, por lo tanto, producirán un error. La función más similar disponible son las importaciones de subrutas con la limitación de que deben comenzar con #.