Source Maps no Node.js

Source maps conectam o JavaScript executado ao código-fonte original. Elas são essenciais quando um projeto usa TypeScript, transpilers, bundlers, minificação ou transformações. Sem essa relação, uma exceção em produção pode apontar para uma linha do arquivo compilado que não corresponde ao código escrito pela equipe.

No Node.js, source maps melhoram stack traces, relatórios de erro e diagnóstico. Entretanto, é preciso gerar mapas corretos, disponibilizá-los ao processo ou à plataforma de observabilidade e proteger o conteúdo quando ele revela código proprietário.

Como um source map funciona

Um arquivo .map contém metadados e mapeamentos entre posições do arquivo gerado e do arquivo original. O JavaScript compilado pode referenciar o mapa por um comentário:

//# sourceMappingURL=server.js.map

O mapa pode apontar para arquivos TypeScript e, opcionalmente, incluir o conteúdo original em sourcesContent.

Ativando source maps no Node.js

node --enable-source-maps dist/server.js

Com a opção habilitada, stack traces tentam usar mapas encontrados para mostrar arquivos e linhas originais.

NODE_OPTIONS

NODE_OPTIONS="--enable-source-maps" node dist/server.js

Essa forma ajuda em ambientes onde o comando é definido por plataforma. Evite sobrescrever outras opções necessárias e registre a configuração efetiva no diagnóstico.

TypeScript

No tsconfig.json:

{
  "compilerOptions": {
    "target": "ES2022",
    "module": "NodeNext",
    "outDir": "dist",
    "rootDir": "src",
    "sourceMap": true,
    "inlineSources": true
  }
}

sourceMap cria arquivos externos. inlineSources inclui o conteúdo original no mapa, facilitando ferramentas, mas aumentando tamanho e sensibilidade.

Mapa externo ou inline

Mapas externos ficam em arquivos separados. Mapas inline são incorporados como data URL no JavaScript. Para produção, mapas externos costumam facilitar retenção e acesso controlado. Mapas inline aumentam o artefato e expõem o código a quem acessar o bundle.

Exemplo de exceção

Código TypeScript:

export function calculateTotal(items: Array<{ price: number }>) {
  return items.reduce((total, item) => total + item.price, 0);
}

calculateTotal(undefined as never);

Sem mapa, a pilha aponta para dist/index.js. Com mapa correto, deve apontar para a linha correspondente em src/index.ts.

Testando o build

npm run build
node --enable-source-maps dist/index.js

Não assuma que o mapa funciona porque o arquivo existe. Gere uma exceção conhecida e confirme caminho, linha, coluna e nome de função.

esbuild

esbuild src/server.ts \
  --bundle \
  --platform=node \
  --sourcemap=external \
  --outfile=dist/server.js

Quando há bundle, o mapa precisa representar módulos combinados e transformações. Preserve o mapa da mesma execução do arquivo JavaScript.

SWC

Configure source maps no arquivo do compilador ou na CLI. O nome da opção varia pela ferramenta e versão. Valide uma stack real depois do build e não apenas a presença de .map.

Mapas encadeados

Um código pode passar por TypeScript, Babel e bundler. Cada etapa precisa consumir o mapa anterior e produzir um novo mapa. Se uma ferramenta ignora o mapa de entrada, o resultado final pode apontar para código intermediário.

Caminhos no mapa

Problemas comuns:

• caminho absoluto da máquina de CI;
• prefixo webpack:// ou outro esquema;
• arquivo original não incluído no container;
• sourceRoot incorreto;
• diretório de deploy diferente;
• mapa de outra versão.

Inspecione as propriedades sources, sourceRoot e file.

Container

Um Dockerfile multi-stage pode copiar JavaScript sem mapas:

FROM node:24-alpine AS build
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM node:24-alpine
WORKDIR /app
COPY --from=build /app/dist ./dist
CMD ["node", "--enable-source-maps", "dist/server.js"]

Confirme que dist inclui os mapas. Se você não deseja mantê-los no runtime, envie-os separadamente para a plataforma de erros.

Plataformas de monitoramento

Serviços de error tracking podem receber source maps durante o deploy. Eles usam release, commit ou identificador de artefato para simbolizar stack traces sem expor mapas publicamente.

O processo básico:

1. gerar build e mapas juntos;
2. atribuir release única;
3. enviar mapas;
4. implantar exatamente o mesmo bundle;
5. associar eventos à release;
6. remover mapas públicos quando não necessários.

Versão e integridade

Um mapa quase correto é perigoso porque aponta para a linha errada. Use hash dos arquivos, release imutável e artefatos promovidos entre ambientes. Não faça rebuild separado para produção depois de enviar os mapas.

Stack traces assíncronos

Source maps transformam posições, mas não recriam contexto que nunca esteve na pilha. Para operações assíncronas, combine com tracing, AsyncLocalStorage e logs correlacionados.

Process Reports

Relatórios de processo incluem stack JavaScript em certos eventos. Com mapas disponíveis e configuração correta, a análise pode ser mais próxima do TypeScript original. Preserve mapas da versão do relatório.

CPU profiling

Ferramentas de profiling podem exibir nomes e arquivos gerados. Algumas suportam source maps; outras exigem processamento posterior. Não assuma que --enable-source-maps transforma automaticamente todos os formatos de profiler.

Minificação em backend

Minificar código Node.js raramente é necessário para reduzir transferência. Pode dificultar profiling, stack traces e debugging. Se usar por proteção ou tamanho de imagem, source maps privados tornam-se ainda mais importantes.

Segurança

Mapas com sourcesContent podem conter o código-fonte completo, comentários, endpoints internos e nomes de arquivos. Não sirva .map publicamente por padrão.

Medidas:

• armazenamento privado;
• controle de acesso;
• criptografia;
• retenção por release;
• exclusão após prazo;
• revisão de segredos;
• bloqueio no servidor web.

Segredos no código

Source maps não criam o problema: segredos nunca deveriam estar no código. Ainda assim, comentários e constantes podem revelar informação. Use secret manager e scanning no CI.

Desempenho

A preparação de stack trace com mapas pode adicionar custo, principalmente em aplicações que criam erros com frequência. Exceção não deve ser usada como fluxo normal. Meça overhead e evite gerar milhares de stacks por segundo.

StackTraceLimit

Error.stackTraceLimit = 50;

Aumentar o limite traz contexto, mas cresce custo e volume. Escolha um valor adequado para diagnóstico.

Logs estruturados

try {
  await operation();
} catch (error) {
  logger.error({
    error: {
      name: error.name,
      message: error.message,
      stack: error.stack,
      cause: error.cause,
    },
  }, 'Operação falhou');
  throw error;
}

O logger precisa preservar a pilha já simbolizada. Não serialize Error com JSON.stringify esperando campos não enumeráveis.

Testes automatizados

Crie um smoke test de stack:

import assert from 'node:assert/strict';

try {
  throwFromTypeScriptSource();
} catch (error) {
  assert.match(error.stack, /src\/example\.ts:/);
}

Execute no artefato compilado com a mesma opção de produção. Evite depender de linha exata se o teste muda com frequência; ainda assim, valide em release antes de confiar.

CI/CD

Checklist:

1. limpar diretório de saída;
2. compilar uma única vez;
3. confirmar mapas;
4. calcular release e hashes;
5. enviar mapas ao sistema privado;
6. empacotar o mesmo JavaScript;
7. executar smoke test;
8. registrar release no runtime.

Bibliotecas

Ao publicar pacote npm, source maps ajudam consumidores a diagnosticar. Inclua apenas arquivos necessários no pacote e confirme que caminhos relativos funcionam depois da instalação.

Source map inválido

Se a pilha não muda:

• confirme --enable-source-maps;
• confirme comentário sourceMappingURL;
• confirme arquivo no caminho;
• abra o JSON e valide formato;
• confirme que mapa e JS são da mesma build;
• teste caminho sem bundle;
• verifique transformação encadeada;
• confirme suporte da ferramenta.

Erros comuns

• gerar mapa e não copiá-lo;
• enviar mapa de outra build;
• expor sourcesContent publicamente;
• fazer rebuild após upload;
• ignorar mapas entre transformações;
• usar caminhos absolutos frágeis;
• minificar backend sem necessidade;
• não testar uma stack real;
• achar que source map substitui tracing.

Fluxo recomendado

Gere mapas na mesma build, habilite-os no runtime ou envie a uma plataforma privada, use releases imutáveis e valide com uma exceção conhecida. Combine com esbuild no Node.js, SWC no Node.js, Process Reports e CPU Profiling.

Consulte a documentação oficial de –enable-source-maps e a referência oficial de sourceMap no TypeScript.