Node.js
Uso de TypeScript nativo en Node.js, sus límites de ejecución, type stripping, configuración compatible y diferencias frente a transpilers y herramientas de build.
Node.js moderno puede ejecutar ciertos archivos TypeScript directamente mediante type stripping: elimina sintaxis de tipos y ejecuta el JavaScript restante. Esto reduce tooling para scripts y servicios sencillos, pero no reemplaza al compilador de TypeScript, no realiza type checking y no transforma todas las características del lenguaje.
archivo .ts
→ Node reconoce sintaxis TypeScript erasable
→ elimina anotaciones de tipos
→ ejecuta JavaScript resultante
archivo .ts
→ tsc / editor
→ comprueba tipos y contratosSon procesos distintos. Que Node ejecute un archivo no significa que el código sea type-safe.
Node elimina sintaxis que no tiene efecto runtime:
function greet(name: string): string {
return `Hola, ${name}`;
}
const user: { name: string } = { name: "Nicolás" };
console.log(greet(user.name));Después de retirar tipos, el runtime ejecuta una forma equivalente a:
function greet(name) {
return `Hola, ${name}`;
}
const user = { name: "Nicolás" };
console.log(greet(user.name));No genera archivos .js, source maps de build ni declaraciones .d.ts por sí mismo.
paths de tsconfig.json como un bundler..d.ts.const port: number = "3000";El compilador marca el error; Node puede eliminar la anotación y ejecutar el valor string si no se comprobó antes.
Funciona bien con sintaxis que desaparece completamente:
as assertions.satisfies.interface Config {
port: number;
}
const config = { port: 3000 } satisfies Config;Algunas construcciones producen JavaScript y no pueden resolverse solo borrando tipos:
enum.class User {
constructor(public id: string) {}
}Esa propiedad necesita código generado. Para estos casos usa una opción de transformación soportada por la versión o un compilador/toolchain explícito.
.ts: módulo TypeScript según package scope y reglas de Node..mts: fuerza ESM..cts: fuerza CommonJS..tsx: no está soportado por el type stripping nativo porque JSX requiere transformación.Mantén explícito el sistema de módulos mediante type, extensiones y exports.
En ejecución directa, los specifiers deben apuntar a archivos reales:
import { loadConfig } from "./config.ts";Node no convierte automáticamente ./config.js hacia config.ts durante ejecución directa.
TypeScript puede requerir configuración compatible para aceptar extensiones .ts:
{
"compilerOptions": {
"module": "nodenext",
"moduleResolution": "nodenext",
"allowImportingTsExtensions": true,
"verbatimModuleSyntax": true,
"erasableSyntaxOnly": true,
"noEmit": true,
"strict": true
}
}erasableSyntaxOnly ayuda a detectar sintaxis que Node no puede ejecutar únicamente retirando tipos.
Marca importaciones que solo existen para tipos:
import type { User } from "./user.ts";
import { createUser } from "./user.ts";Con verbatimModuleSyntax, el compilador preserva la intención y evita que una importación runtime desaparezca o se mantenga de forma inesperada.
Node no usa la mayoría de opciones de tsconfig para ejecutar el archivo. El archivo sigue siendo valioso para:
Flujo recomendado:
node src/index.ts → ejecución
tsc --noEmit → comprobación estática
node --test → comportamiento{
"compilerOptions": {
"paths": {
"@/*": ["./src/*"]
}
}
}Node no resuelve esos aliases por defecto. Usa:
package.json#imports con prefijos #.{
"imports": {
"#config": "./src/config.ts"
}
}import { config } from "#config";Esto mantiene la resolución alineada con Node.
Aunque Node pueda ejecutar .ts, conserva:
npx tsc --noEmit
node --testEl runtime detecta errores de ejecución; el compilador detecta contratos incompatibles antes de ejecutar.
Un pipeline mínimo:
install reproducible
→ lint
→ tsc --noEmit
→ node --test
→ execute/packageEjecutar TypeScript directo puede ser apropiado cuando:
Compilar sigue siendo útil cuando necesitas:
Una librería publicada no debería asumir que todos los consumidores ejecutarán TypeScript fuente. Normalmente publica:
dist/
├─ index.js
├─ index.d.ts
└─ package.json exportsDefine ESM/CJS conscientemente y prueba el package instalado, no solo el source workspace.
El test runner puede ejecutar tests .ts compatibles con type stripping:
import test from "node:test";
import assert from "node:assert/strict";
test("suma", () => {
const values: number[] = [10, 20];
assert.equal(values.reduce((a, b) => a + b, 0), 30);
});Sigue ejecutando tsc --noEmit; el test no valida todos los tipos.
Distingue:
SyntaxError / unsupported syntax
→ Node no pudo ejecutar la construcción
Type error
→ tsc detectó contrato incompatible
Runtime error
→ JavaScript ejecutado falló
Module resolution error
→ specifier/extensión/package scope incorrectosNo resuelvas un error de módulo cambiando aleatoriamente entre CJS y ESM.
TypeScript no valida input runtime:
const body = JSON.parse(text) as CreateOrderInput;La assertion solo cambia la visión del compilador. Usa un schema runtime para requests, archivos, env y mensajes externos.
Herramientas como tsx pueden aportar:
Pero añaden una dependencia y semántica propia. Elige entre Node directo, runner, tsc, SWC o bundler según el problema, no por costumbre.
No: elimina tipos y ejecuta JavaScript compatible.
Pierdes type checking.
Node no los reconoce automáticamente.
Falla en ejecución directa.
La sintaxis necesita generar JavaScript.
Traslada requisitos de tooling al consumidor.
No existen en runtime.
.mts y .cts para módulos explícitos cuando aporte..tsx necesita transformación.tsconfig sigue siendo necesario para strictness y CI.package.json#imports es preferible a aliases invisibles para Node.tsc?enum no puede simplemente borrarse?paths de tsconfig?.ts no garantiza type safety?.mts.Modelo mental completo de Node.js integra ejecución, recursos, TypeScript, concurrencia, seguridad y producción.