Debugar TypeScript: Source Maps e VS Code
Pare de debugar com console.log. Aprenda a usar source maps, VS Code debugger, breakpoints e launch.json pra encontrar bugs em TypeScript rápido.
Por que isso é importante
Debugar TypeScript: Source Maps e VS Code. Pare de debugar com console.log. Aprenda a usar source maps, VS Code debugger, breakpoints e launch.json pra encontrar bugs em TypeScript rápido.
O Que São Source Maps e Por Que Você Precisa Deles
Source maps são arquivos .map que fazem a ponte entre o JavaScript compilado e o TypeScript original. Quando o runtime encontra um erro na linha 42 do arquivo .js, o source map diz: 'na verdade, isso é a linha 87 do arquivo .ts'.
Sem source maps, debugar TypeScript é como tentar ler um livro traduzido sem saber a língua original. Os breakpoints não batem, as variáveis têm nomes diferentes e o fluxo do código fica confuso.
Com source maps ativados, o VS Code debugger mostra seu código TypeScript original, com breakpoints exatamente onde você colocou, variáveis com os nomes que você definiu e o fluxo de execução que faz sentido.
Como Configurar Debug no TypeScript Passo a Passo
A configuração tem três partes: habilitar source maps no tsconfig, criar o launch.json no VS Code e aprender a usar breakpoints. Vamos em cada uma.
- Passo 1 - Ative source maps no tsconfig.json: Adicione "sourceMap": true no compilerOptions. Isso gera um arquivo .js.map pra cada .ts compilado. O debugger usa esses arquivos pra mapear de volta pro TypeScript.
- Passo 2 - Crie o launch.json no VS Code: Vá em Run > Add Configuration ou crie .vscode/launch.json manualmente. Configure o tipo de debug (Node.js, Chrome, etc.) com os paths corretos.
- Passo 3 - Configure breakpoints: Clique na margem esquerda do editor (ao lado do número da linha) pra colocar breakpoints. A bolinha vermelha indica onde a execução vai parar.
- Passo 4 - Inicie o debugger: Pressione F5 ou clique em Run > Start Debugging. O código roda até o primeiro breakpoint e para. Você pode inspecionar variáveis, call stack e step through do código.
- Passo 5 - Use Watch Expressions: No painel de debug, adicione expressões que quer monitorar. O valor atualiza em tempo real conforme você avança no código.
- Passo 6 - Configure outFiles pra source maps: No launch.json, o campo outFiles diz pro debugger onde encontrar os source maps. Configure pra apontar pra pasta de build.
Configuração do tsconfig.json Para Debug
O tsconfig precisa de ajustes específicos pra gerar source maps que o debugger consiga usar.
// tsconfig.json - configurações pra debug
{
"compilerOptions": {
"target": "ES2020",
"module": "commonjs",
"outDir": "./dist",
"rootDir": "./src",
"strict": true,
// Source maps - a chave do debug
"sourceMap": true,
// Opcional: inline source maps (tudo num arquivo só)
// "inlineSourceMap": true,
// Opcional: incluir código fonte no source map
// "inlineSources": true,
// Facilita navegação no debugger
"declaration": true,
"declarationMap": true
},
"include": ["src/**/*"],
"exclude": ["node_modules", "dist"]
}
// Depois de compilar (tsc), a pasta dist/ vai ter:
// dist/index.js - código JavaScript
// dist/index.js.map - source map
// dist/index.d.ts - declarações de tipo
// dist/index.d.ts.map - mapa das declarações
O sourceMap: true gera arquivos .js.map separados. Se preferir, use inlineSourceMap: true pra embutir o mapa dentro do próprio .js. Inline é mais simples mas aumenta o tamanho do arquivo.
Configuração do launch.json Para Node.js
O launch.json é o coração do debug no VS Code. Ele diz pro editor como iniciar seu programa e onde encontrar os source maps.
Debug de Aplicação Node.js Compilada
// .vscode/launch.json
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug TypeScript (compilado)",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/dist/index.js",
"outFiles": ["${workspaceFolder}/dist/**/*.js"],
"sourceMaps": true,
"console": "integratedTerminal",
"preLaunchTask": "tsc: build - tsconfig.json"
}
]
}
// O que cada campo faz:
// program: arquivo de entrada JavaScript
// outFiles: onde estão os .js e .js.map
// sourceMaps: ativar resolução de source maps
// preLaunchTask: compilar antes de debugar
// console: usar terminal integrado pra I/O
Debug com ts-node (Sem Compilar)
// .vscode/launch.json - usando ts-node
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug TypeScript (ts-node)",
"type": "node",
"request": "launch",
"runtimeExecutable": "node",
"runtimeArgs": [
"--require", "ts-node/register"
],
"args": ["${workspaceFolder}/src/index.ts"],
"sourceMaps": true,
"console": "integratedTerminal",
"resolveSourceMapLocations": [
"${workspaceFolder}/**",
"!**/node_modules/**"
]
},
{
"name": "Debug Arquivo Atual",
"type": "node",
"request": "launch",
"runtimeExecutable": "node",
"runtimeArgs": [
"--require", "ts-node/register"
],
"args": ["${file}"],
"sourceMaps": true,
"console": "integratedTerminal"
}
]
}
// A config "Debug Arquivo Atual" debuga qualquer .ts que
// estiver aberto no editor. Muito útil pra testar isolado.
A abordagem com ts-node é mais prática no desenvolvimento: não precisa compilar antes de debugar. Pra produção, debug com código compilado é mais fiel ao que roda no servidor.
Tipos de Breakpoint no VS Code
Breakpoints vão muito além da bolinha vermelha. O VS Code tem breakpoints condicionais, logpoints e mais. Conhecer cada tipo poupa horas de debug.
// 1. Breakpoint Normal (clique na margem esquerda)
// Para a execução naquela linha.
// 2. Breakpoint Condicional (clique direito > Conditional)
// Só para se a condição for true.
// Exemplo: users.length > 100
// Útil em loops - para só na iteração que importa.
// 3. Logpoint (clique direito > Logpoint)
// Não para a execução - só loga no console.
// Exemplo: "User {user.name} processed at {Date.now()}"
// Substitui console.log sem modificar o código.
// 4. Hit Count Breakpoint (clique direito > Hit Count)
// Para depois de N execuções.
// Exemplo: 50 (para na 50ª vez que passa ali)
// 5. Exception Breakpoints (no painel de debug)
// Para quando qualquer exceção é lançada.
// Ativar: Debug sidebar > Breakpoints > Caught/Uncaught
// Atalhos de navegação durante debug:
// F5 = Continue (até próximo breakpoint)
// F10 = Step Over (próxima linha, sem entrar em funções)
// F11 = Step Into (entra na função)
// Shift+F11 = Step Out (sai da função atual)
// Ctrl+Shift+F5 = Restart debug session
Logpoints são ouro puro. Em vez de adicionar console.log, recompilar e rodar de novo, você adiciona um logpoint sem tocar no código. Ele loga o que você quer e some quando você fecha o debug. Zero sujeira no código.
Debug de Testes Jest com TypeScript
Debugar testes que falham é um dos cenários mais comuns. O VS Code consegue rodar Jest com debugger anexado.
// .vscode/launch.json - config pra debug de testes
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug Jest Tests",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": [
"jest",
"--runInBand",
"--no-cache"
],
"sourceMaps": true,
"console": "integratedTerminal",
"internalConsoleOptions": "neverOpen"
},
{
"name": "Debug Teste Atual",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": [
"jest",
"--runInBand",
"--no-cache",
"${fileBasenameNoExtension}"
],
"sourceMaps": true,
"console": "integratedTerminal"
}
]
}
// --runInBand: roda testes em série (necessário pra debug)
// --no-cache: evita problemas com cache do ts-jest
// ${fileBasenameNoExtension}: nome do arquivo aberto sem extensão
Com a config 'Debug Teste Atual', abra o arquivo de teste no editor e pressione F5. O Jest roda só aquele arquivo com debugger. Coloque breakpoints no teste e no código fonte — o debugger para nos dois.
Debug no Browser com TypeScript
Pra projetos frontend (React, Vue, Angular), o debug acontece no browser. O VS Code consegue controlar o Chrome e debugar TypeScript direto no editor.
// .vscode/launch.json - debug no Chrome
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug no Chrome",
"type": "chrome",
"request": "launch",
"url": "http://localhost:3000",
"webRoot": "${workspaceFolder}/src",
"sourceMaps": true,
"sourceMapPathOverrides": {
"webpack:///src/*": "${webRoot}/*"
}
},
{
"name": "Debug Next.js",
"type": "node",
"request": "launch",
"runtimeExecutable": "npx",
"runtimeArgs": ["next", "dev"],
"sourceMaps": true,
"console": "integratedTerminal",
"serverReadyAction": {
"pattern": "ready on",
"uriFormat": "http://localhost:3000",
"action": "debugWithChrome"
}
}
]
}
// A config "Debug Next.js" inicia o dev server e abre o Chrome
// com debugger automaticamente. Breakpoints funcionam tanto no
// server (API routes) quanto no client (components).
Com o debug de Next.js configurado, dá pra colocar breakpoints em Server Components, API Routes e Client Components — tudo no mesmo editor. O VS Code detecta onde cada parte roda e direciona o debugger correto.
Erros Comuns ao Debugar TypeScript
Armadilhas do debug
Breakpoint aparece cinza com 'Unverified breakpoint': o source map não tá mapeando corretamente. Verifique se sourceMap: true tá no tsconfig e se outFiles no launch.json aponta pra pasta certa dos arquivos compilados.
Variáveis mostram undefined quando deveriam ter valor: o código pode estar otimizado ou minificado. Em desenvolvimento, desative minificação e use target ES2020+ no tsconfig pra manter o código próximo do original.
Step Into entra em arquivos de node_modules: configure skipFiles no launch.json com ["
Debug funciona mas para no JavaScript em vez do TypeScript: os source maps estão sendo ignorados. Verifique se os arquivos .js.map existem na pasta de build e se o path no final do .js aponta pro .map correto.
Console.log como vício: usar console.log não é debugar, é adivinhar. Breakpoints condicionais e logpoints fazem a mesma coisa sem sujar o código e com muito mais contexto (call stack, variáveis locais, scope).
Checklist de Debug TypeScript
- sourceMap: true ativado no tsconfig.json
- launch.json criado em .vscode/ com configurações de debug
- outFiles apontando pra pasta de build correta
- skipFiles configurado pra ignorar node_modules
- Breakpoints funcionando no código TypeScript (não no .js)
- Configuração de debug pra Jest com --runInBand
- Debug no browser configurado (Chrome ou Edge)
- Logpoints sendo usados em vez de console.log
- Watch expressions configuradas pra variáveis importantes
Debug Profissional com TypeScript
Saber debugar é o que transforma um dev que 'tenta até funcionar' num profissional que encontra e resolve bugs em minutos. No CrazyStack, você aprende debug na prática — breakpoints em APIs Node.js, componentes React e testes Jest. Tudo com TypeScript e source maps configurados.
Pare de adivinhar onde tá o bug. Configure o debugger uma vez e ganhe horas de produtividade em cada sessão de código.
Perguntas frequentes
O Que São Source Maps e Por Que Você Precisa Deles
Source maps são arquivos .map que fazem a ponte entre o JavaScript compilado e o TypeScript original. Quando o runtime encontra um erro na linha 42 do arquivo .js, o source map diz: 'na verdade, isso é a linha 87 do arquivo .ts'. Sem source maps, debugar TypeScript é como tentar ler um livro traduzido sem saber a língua original. Os breakpoints não batem, as variáveis têm nomes diferentes e o fluxo do código fica confuso. Com source maps ativados, o VS Code debugger mostra seu código TypeScript original, com breakpoints exatamente onde você colocou, variáveis com os nomes que você definiu e o fluxo de execução que faz sentido.
Como Configurar Debug no TypeScript Passo a Passo
A configuração tem três partes: habilitar source maps no tsconfig, criar o launch.json no VS Code e aprender a usar breakpoints. Vamos em cada uma.