Como monitorar o ts-node e recarregar ao alterar arquivos: guia de erros

Como fazer o ts-node recarregar ao alterar arquivos: análise dos problemas reais

Imagine: você está escrevendo um servidor em TypeScript, inicia o ts-node, faz uma alteração — e nada acontece. Você precisa parar o processo manualmente, apertar Ctrl+C e iniciar novamente. Familiar? Esse problema acumulou milhares de visualizações no Stack Overflow, e não é à toa: configurar o watch e reload para ts-node é um verdadeiro quebra-cabeça.

Neste artigo, não vou apenas dar uma receita pronta. Vamos analisar os principais erros que até desenvolvedores experientes cometem, e mostrarei como evitá-los. Você aprenderá por que ts-node --watch não funciona "de fábrica", como ts-node-dev é melhor que a abordagem clássica e como não prejudicar o desempenho do servidor no processo.

Por que o ts-node não recarrega sozinho?

Vamos esclarecer isso de uma vez. ts-node não é um servidor de desenvolvimento. É um transpilador de TypeScript para JavaScript que executa o código no runtime do Node.js. Ele não possui um mecanismo interno de monitoramento de alterações de arquivos (file watcher). Quando você executa ts-node app.ts, ele simplesmente executa o arquivo e encerra.

Para obter recarga automática ao alterar arquivos, você precisa usar ferramentas externas. E é aqui que a coisa fica interessante.

Os 5 principais erros ao configurar watch e reload para ts-node

Reuni os problemas mais comuns que os desenvolvedores enfrentam. Vamos analisar cada um com exemplos e soluções.

Erro nº1: Usar a flag --watch sem a ferramenta correta

Muitos escrevem no terminal:

ts-node --watch app.ts

E se surpreendem que nada funciona. O problema é que o ts-node não possui a flag --watch na instalação padrão. Esse comando é simplesmente ignorado ou gera um erro.

Solução: Use o nodemon em conjunto com o ts-node. Aqui está o comando correto:

npx nodemon --exec ts-node app.ts

Ou, se preferir salvar no package.json:

{  "scripts": {    "dev": "nodemon --exec ts-node src/index.ts"  }}

Isso fará com que o nodemon monitore as alterações nos arquivos e reinicie o ts-node a cada salvamento.

Erro nº2: nodemon não detecta alterações em arquivos .ts

Você configurou o nodemon, salva o arquivo, mas ele não reage. Por quê? Por padrão, o nodemon monitora apenas arquivos .js, .json e algumas outras extensões. .ts não está na lista.

Solução: Especifique as extensões explicitamente:

nodemon --watch src --ext ts --exec ts-node src/index.ts

A flag --watch src limita o escopo do monitoramento à pasta src (para não monitorar o node_modules). E --ext ts adiciona os arquivos TypeScript à lista de extensões monitoradas.

Você também pode criar um nodemon.json:

{  "watch": ["src"],  "ext": "ts",  "exec": "ts-node src/index.ts"}

Erro nº3: Conflito com tsconfig.json — module resolution incorreto

Situação típica: você usa ts-node com nodemon, mas ao iniciar recebe erros como Cannot find module ou Unknown file extension ".ts". Na maioria das vezes, o problema está nas configurações do tsconfig.json.

Exemplo de tsconfig.json problemático:

{  "compilerOptions": {    "module": "ESNext",    "moduleResolution": "bundler",    "target": "ES2020"  }}

Problema: o ts-node funciona no ambiente Node.js, e module: "ESNext" com moduleResolution: "bundler" são projetados para bundlers como Webpa