¿El archivo .ts de TypeScript no funciona? Solución al error "Unknown file extension"

Introducción: "¿Su archivo .ts no se abre? No está solo"

Imagine: está escribiendo código genial en TypeScript, guarda el archivo con la extensión .ts, ejecuta el comando node myfile.ts... y recibe algo como: "Unknown file extension ".ts". ¿Le suena familiar? Si ha mirado en Stack Overflow, sabrá que esta pregunta ha acumulado miles de visitas y cientos de comentarios. El problema es antiguo, pero sigue siendo relevante.

En este artículo no solo copiaremos una respuesta de un foro. Analizaremos por qué ocurre esto, cómo solucionarlo y qué hacer para no volver a encontrarse con este error. Aprenderá a configurar correctamente un proyecto TypeScript, usar ts-node y la configuración tsconfig.json. ¡Allá vamos!

¿Por qué ocurre el error "Unknown file extension ".ts"?

Vayamos al grano. Node.js no entiende los archivos .ts por defecto. Solo reconoce .js, .json, .mjs y .cjs. Cuando escribe node myfile.ts, Node.js intenta ejecutar el código TypeScript como si fuera JavaScript normal, pero se encuentra con una sintaxis que no conoce (por ejemplo, tipos, interfaces, genéricos).

El resultado es un error. Pero también hay otra situación: usa ts-node o tsx, pero aún así ve el mismo mensaje. ¿Por qué? Porque en las versiones modernas de Node.js (a partir de la 16) se agregó una verificación estricta de extensiones en package.json, especialmente cuando está configurado "type": "module".

Causas principales:

\n
• Ejecución directa de node file.ts — Node.js no sabe compilar TypeScript sobre la marcha.
\n
• Falta de ts-node o tsx — no hay una herramienta para la transpilación.
\n
• Configuración incorrecta de tsconfig.json — por ejemplo, no se especificó el módulo o el target.
\n
• Problemas con package.json — si tiene "type": "module", ts-node puede requerir la extensión explícita.
\n

Solución 1: Usar ts-node (método clásico)

La forma más sencilla de ejecutar TypeScript sin compilación previa es usar ts-node. Este paquete compila los archivos .ts en memoria y pasa el resultado a Node.js.

Instalación y ejecución

npm install -g ts-node\nts-node myfile.ts

Si usa un proyecto local, es mejor instalarlo como dependencia de desarrollo:

npm install --save-dev ts-node\nnpx ts-node myfile.ts

Ejemplo de un archivo simple hello.ts:

const greet = (name: string): string => {\n    return `¡Hola, ${name}!`;\n};\n\nconsole.log(greet("Mundo"));

Ejecutamos: npx ts-node hello.ts — y vemos en la consola "¡Hola, Mundo!". ¡Funciona!

Pero hay un detalle: "type": "module"

Si en su package.json está especificado "type": "module", ts-node puede negarse a funcionar. En ese caso, debe eliminar temporalmente esa línea o usar el flag --esm:

npx ts-node --esm myfile.ts

Solución 2: Usar tsx (herramienta moderna)

tsx es una alternativa más rápida a ts-node, basada en esbuild. Funciona con ESM de fábrica y no requiere flags adicionales.

Instalación:

npm install --save-dev tsx

Ejecución:

npx tsx myfile.ts

Ejemplo usando características modernas de TypeScript:

// types.ts\nexport interface User {\n    id: number;\n    name: string;\n    email: string;\n}\n\nconst user