Debugging TypeScript no VS Code

Depurar código TypeScript pode parecer complexo devido à camada de transpilação para JavaScript, mas o VS Code oferece ferramentas robustas que tornam esse processo transparente e eficiente. Neste artigo, você aprenderá a configurar e utilizar o depurador integrado para inspecionar, rastrear e corrigir erros em suas aplicações TypeScript diretamente no editor.

1. Configuração Inicial do Ambiente de Debug

Para iniciar, certifique-se de ter o Node.js instalado e o VS Code com suporte a TypeScript (já incluso nativamente). Crie um projeto simples:

// src/index.ts
function greet(name: string): string {
  return `Hello, ${name}!`;
}

const message = greet("TypeScript");
console.log(message);

Compile com tsc e depois crie o arquivo de configuração de debug. Pressione Ctrl+Shift+D e clique em "create a launch.json file". Selecione Node.js. O VS Code gerará algo similar a:

{
  "version": "0.2.0",
  "configurations": [
    {
      "type": "node",
      "request": "launch",
      "name": "Debug TypeScript",
      "skipFiles": ["<node_internals>/**"],
      "program": "${workspaceFolder}/src/index.ts",
      "outFiles": ["${workspaceFolder}/dist/**/*.js"],
      "preLaunchTask": "tsc: build - tsconfig.json"
    }
  ]
}
  • program: aponta para o arquivo TypeScript de entrada.
  • outFiles: diretório onde os arquivos compilados (JS + source maps) serão gerados.
  • preLaunchTask: executa a compilação automaticamente antes de iniciar o debug.

Para debug no navegador, use a extensão Debugger for Chrome e configure type: "chrome" com a URL da sua aplicação.

2. Source Maps: A Ponte entre TypeScript e JavaScript

Source maps são arquivos .map que mapeiam o código JavaScript gerado de volta ao TypeScript original. Sem eles, o depurador mostraria apenas o JS transpilado, impossibilitando breakpoints nos arquivos .ts.

No tsconfig.json, ative a geração:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "commonjs",
    "outDir": "./dist",
    "rootDir": "./src",
    "sourceMap": true,
    "strict": true
  }
}

Após compilar, verifique se o diretório dist contém arquivos .js e .js.map correspondentes. O depurador do VS Code lê automaticamente esses mapas para associar as linhas do JS ao TypeScript.

3. Breakpoints e Navegação no Código TypeScript

Com os source maps configurados, você pode clicar na margem esquerda de qualquer arquivo .ts para adicionar um breakpoint (ponto vermelho). Execute o debug pressionando F5.

Breakpoints Condicionais

Clique com o botão direito no breakpoint e selecione "Edit Breakpoint". Insira uma expressão como:

name === "TypeScript"

O debug só pausará quando a condição for verdadeira.

Logpoints

Em vez de pausar, um logpoint exibe uma mensagem no console de debug. Útil para rastrear valores sem interromper o fluxo:

{name} foi chamado
  • Step Over (F10): executa a linha atual e vai para a próxima, sem entrar em funções.
  • Step Into (F11): entra em uma chamada de função para depurar seu interior.
  • Step Out (Shift+F11): sai da função atual e retorna ao contexto anterior.

4. Inspeção de Variáveis e Expressões

Durante a pausa, o painel VARIABLES exibe:

  • Locals: variáveis do escopo atual.
  • Closure: variáveis de closures.
  • Globals: variáveis globais (como console, process).

Para monitorar expressões específicas, use o painel WATCH. Clique no ícone + e digite, por exemplo:

message.toUpperCase()

O valor será atualizado a cada pausa.

O DEBUG CONSOLE permite avaliar expressões TypeScript em tempo real. Durante a pausa, digite:

> greet("World")
"Hello, World!"

5. Debug de Aplicações com Dependências e Módulos

Projetos TypeScript geralmente usam módulos (ESM ou CommonJS). O depurador lida bem com importações, mas é importante configurar corretamente.

Para projetos ESM, ajuste o launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Debug ESM",
  "runtimeArgs": ["--experimental-modules"],
  "program": "${workspaceFolder}/src/index.ts",
  "outFiles": ["${workspaceFolder}/dist/**/*.mjs"]
}

Evite depurar dentro de node_modules adicionando ao launch.json:

"skipFiles": ["${workspaceFolder}/node_modules/**/*.js", "<node_internals>/**"]

Isso acelera o debug e evita confusão com código de terceiros.

6. Debug de Testes TypeScript

Testes são parte essencial do desenvolvimento. Configure o debug para frameworks populares:

Jest

Crie uma configuração no launch.json:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Jest Tests",
  "program": "${workspaceFolder}/node_modules/jest/bin/jest",
  "args": ["--runInBand", "--config", "jest.config.ts"],
  "console": "integratedTerminal",
  "internalConsoleOptions": "neverOpen"
}

Agora você pode inserir breakpoints em arquivos .test.ts e executar os testes com F5.

Vitest

Configuração similar:

{
  "type": "node",
  "request": "launch",
  "name": "Debug Vitest",
  "program": "${workspaceFolder}/node_modules/vitest/vitest.mjs",
  "args": ["--run"],
  "console": "integratedTerminal"
}

Exemplo de teste com breakpoint:

// src/calculator.test.ts
import { describe, it, expect } from 'vitest';
import { add } from './calculator';

describe('Calculator', () => {
  it('should add two numbers', () => {
    const result = add(2, 3); // Coloque um breakpoint aqui
    expect(result).toBe(5);
  });
});

7. Dicas Avançadas e Troubleshooting

Debug de Código Assíncrono

Promises e async/await funcionam perfeitamente. O depurador pausa em await e permite inspecionar o estado antes e depois da resolução:

async function fetchData(url: string): Promise<any> {
  const response = await fetch(url); // Breakpoint aqui
  return response.json();
}

Problemas Comuns e Soluções

Problema Solução
Breakpoints não atingidos Verifique se sourceMap: true e se os arquivos .map estão no outDir
"Cannot find module" Certifique-se de que outFiles no launch.json corresponde ao outDir do tsconfig.json
Debug lento Adicione "skipFiles": ["**/node_modules/**"]
Erro de permissão no navegador Use o modo headless ou extensão Debugger for Chrome

Extensões Recomendadas

  • Debugger for Chrome — debug de aplicações front-end no Chrome.
  • Live Server — servidor local com reload automático para testes rápidos.
  • TypeScript Hero — auxílio na organização de imports e refatoração.

Referências