Depuração de código TypeScript: ferramentas e técnicas para o desenvolvedor

Depuração de código TypeScript: transformando bugs em tarefas

Você já passou uma hora procurando um erro que era apenas um simples erro de digitação no nome de uma variável? Ou se pegou pensando que console.log é a única ferramenta que você usa? Bem-vindo ao clube. A depuração não é apenas "caçar bugs", mas toda uma arte de entender como seu código realmente funciona.

O TypeScript adiciona um charme especial a essa história. Por um lado, a tipagem estática elimina toda uma classe de erros ainda na fase de compilação. Por outro lado, quando o código já está compilado em JavaScript, depurá-lo "em tempo real" se torna mais difícil: você escreve em TS, mas vê no navegador o JS compilado. Como não se perder nesse labirinto?

Hoje vou mostrar a você técnicas reais de depuração de código TypeScript que eu mesmo uso. Nada de enrolação — apenas ferramentas práticas, exemplos e dicas que vão economizar seus nervos e horas de trabalho.

Por que a depuração do TypeScript é diferente da depuração do JavaScript?

A principal característica do TypeScript é a transpilação. Você escreve código com tipos, genéricos e interfaces, e o navegador ou Node.js recebem JavaScript puro. Isso significa que, ao depurar, você está olhando para o código compilado, que pode ser muito diferente do original: nomes de variáveis podem ser alterados, genéricos são apagados e interfaces desaparecem completamente.

Solução — Source Maps. São mapas de correspondência entre o TS original e o JS compilado. Sem eles, a depuração do TypeScript se torna um jogo de adivinhação.

Configuração de Source Maps: o primeiro passo para a transparência

Para que o navegador ou o depurador entendam a qual linha do TS corresponde uma linha do JS, é necessário ativar a geração de source maps no tsconfig.json:

{\n  "compilerOptions": {\n    "sourceMap": true,\n    "outDir": "./dist",\n    "target": "ES2020",\n    "module": "commonjs"\n  },\n  "include": ["src/**/*"]\n}

Agora, ao compilar, ao lado de cada arquivo JS será gerado um arquivo .map. O navegador (Chrome, Firefox) o carregará automaticamente, e você poderá definir pontos de parada diretamente no código TypeScript.

Importante: em produção, é melhor desativar os source maps ou usar endpoints ocultos para não expor o código-fonte aos usuários. Configure isso através de variáveis de ambiente:

// tsconfig.prod.json\n{\n  "extends": "./tsconfig.json",\n  "compilerOptions": {\n    "sourceMap": false\n  }\n}

Ferramentas de depuração TypeScript: seu arsenal

1. VS Code — depurador integrado

O Visual Studio Code é, sem dúvida, o melhor ambiente para depuração de TypeScript. O depurador integrado consegue ler source maps e definir breakpoints diretamente nos arquivos .ts. Aqui está uma configuração mínima do launch.json:

{\n  "version": "0.2.0",\n  "configurations": [\n    {\n      "type": "node",\n      "request": "launch",\n      "name": "Depuração TS via ts-node",\n      "runtimeArgs": ["-r", "ts-node/register"],\n      "args": ["${workspaceFolder}/src/index.ts"],\n      "sourceMaps": true,\n      "cwd": "${workspaceFolder}",\n      "protocol": "inspector"\n    }\n  ]\n}

Agora você pode pressionar F5 e entrar imediatamente no depurador. Coloque pontos vermelhos à esquerda dos números das linhas — eles funcionarão mesmo se você estiver depurando código TypeScript com genéricos e decoradores.

Dica: use debugger; diretamente no código — é equivalente a definir um breakpoint, mas não requer o uso do mouse.

2. Chrome DevTools — depuração de frontend

Para projetos frontend em TypeScript (React, Angular, Vue), o Chrome DevTools é indispensável. Abra a aba Sources, encontre seu arquivo na pasta webpack:// ou src — se os source maps estiverem configurados corretamente, você verá o TypeScript original.

Recursos úteis:

\n
• Conditional breakpoints