Arquivo .ts do TypeScript não funciona? Solução para o erro "Unknown file extension"

Introdução: "Seu arquivo .ts não abre? Você não está sozinho"

Imagine: você escreve um código legal em TypeScript, salva o arquivo com a extensão .ts, executa o comando node myfile.ts... e recebe algo como: "Unknown file extension ".ts". Familiar? Se você já deu uma olhada no Stack Overflow, sabe que essa pergunta acumulou milhares de visualizações e centenas de comentários. O problema é antigo, mas ainda atual.

Neste artigo, não vamos apenas copiar uma resposta do fórum. Vamos analisar por que isso acontece, como corrigir e o que fazer para nunca mais enfrentar esse erro. Você aprenderá como configurar corretamente um projeto TypeScript, usar ts-node e a configuração tsconfig.json. Vamos lá!

Por que ocorre o erro "Unknown file extension ".ts"?

Vamos direto ao ponto. O Node.js, por padrão, não entende arquivos .ts. Ele só conhece .js, .json, .mjs e .cjs. Quando você escreve node myfile.ts, o Node.js tenta honestamente executar o código TypeScript como JavaScript comum, mas encontra uma sintaxe que não lhe é familiar (por exemplo, tipos, interfaces, genéricos).

O resultado é um erro. Mas há outra situação: você usa ts-node ou tsx, mas ainda vê a mesma mensagem. Por quê? Porque nas versões modernas do Node.js (a partir da 16), foi adicionada uma verificação rigorosa de extensões no package.json, especialmente quando está definido "type": "module".

Principais causas:

\n
• Execução direta de node file.ts — Node.js não sabe compilar TypeScript em tempo real.
\n
• Ausência de ts-node ou tsx — não há ferramenta para transpilação.
\n
• Configuração incorreta do tsconfig.json — por exemplo, módulo ou target não especificados.
\n
• Problemas com package.json — se "type": "module" estiver definido, o ts-node pode exigir a especificação explícita da extensão.
\n

Solução 1: Usar ts-node (método clássico)

A maneira mais simples de executar TypeScript sem compilação prévia é usar ts-node. Este pacote compila arquivos .ts na memória e passa o resultado para o Node.js.

Instalação e execução

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

Se você estiver usando um projeto local, é melhor instalá-lo como dependência de desenvolvimento:

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

Exemplo de um arquivo simples hello.ts:

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

Execute: npx ts-node hello.ts — e você verá no console "Olá, Mundo!". Funciona!

Mas há um detalhe: "type": "module"

Se no seu package.json estiver definido "type": "module", o ts-node pode se recusar a funcionar. Nesse caso, você pode remover temporariamente essa linha ou usar a flag --esm:

npx ts-node --esm myfile.ts

Solução 2: Usar tsx (ferramenta moderna)

tsx é uma alternativa mais rápida ao ts-node, baseada no esbuild. Ela funciona com ESM nativamente e não requer flags adicionais.

Instalação:

npm install --save-dev tsx

Execução:

npx tsx myfile.ts

Exemplo usando recursos modernos do TypeScript:

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