Aliases em tsconfig.json: como funcionam os caminhos no TypeScript

Como os aliases no TypeScript economizam horas do seu dia

Você já escreveu algo como import UserService from '../../../../../services/UserService'? Se sim, você conhece essa dor. Os olhos se perdem, a refatoração vira um pesadelo e qualquer movimentação de arquivo quebra toda a cadeia de imports. Felizmente, o TypeScript (e seu arquivo de configuração tsconfig.json) oferece uma solução elegante: os paths.

Mas a pergunta é: como isso funciona por baixo dos panos? Por que, ao definir o alias "@/*", você pode escrever import { UserService } from '@/services/UserService'? E o principal: por que isso às vezes não funciona sem configurações adicionais no bundler (webpack, Vite, Rollup)?

Neste artigo, não vamos apenas mostrar como configurar os paths no tsconfig.json. Vamos mergulhar no mecanismo interno, entender o path mapping, descobrir como o TypeScript resolve módulos e aprender a evitar erros típicos.

O que são paths no tsconfig.json?

Paths é uma seção no tsconfig.json que permite criar mapeamentos personalizados entre apelidos de importação e caminhos reais para arquivos. Em outras palavras, você diz ao TypeScript: "Quando encontrar um import começando com @utils/, na verdade procure o arquivo na pasta src/utils/".

Veja como fica no código:

// tsconfig.json\n{\n  "compilerOptions": {\n    "baseUrl": ".",\n    "paths": {\n      "@/*": ["src/*"],\n      "@utils/*": ["src/utils/*"],\n      "@components/*": ["src/components/*"]\n    }\n  }\n}\n

Agora, em vez dos terríveis caminhos relativos, você escreve:

// Antes (pesadelo)\nimport { formatDate } from '../../../../utils/dateHelpers';\n\n// Depois (beleza)\nimport { formatDate } from '@utils/dateHelpers';\n

Concorda que a diferença é enorme? Mas como o TypeScript sabe para onde ir?

Como funciona a resolução de módulos por baixo dos panos

Para entender o path mapping no TypeScript, é preciso conhecer o mecanismo básico de resolution (resolução de módulos). Quando o TypeScript compila seu código, ele usa uma estratégia semelhante à do Node.js, mas com recursos adicionais.

O processo funciona assim:

\n
1. Verificação de caminho absoluto (começa com /) — se for o caso, busca a partir da raiz do sistema de arquivos.
\n
2. Verificação de caminho relativo (começa com ./ ou ../) — resolve em relação ao arquivo atual.
\n
3. Verificação de alias do paths — se o import começar com um prefixo definido em paths, o TypeScript substitui pelo caminho correspondente no mapeamento.
\n
4. Busca em node_modules — se nada funcionar, procura o módulo como um pacote npm.
\n

Ponto-chave: o TypeScript não altera os caminhos físicos no JavaScript compilado. Ele apenas verifica os tipos e emite erros se o arquivo não for encontrado. Já a substituição dos aliases pelos caminhos reais em tempo de execução é tarefa do bundler (webpack, Vite, tsc-alias).

Por que os paths não funcionam "de fábrica"?

Essa é a pergunta mais comum no Stack Overflow: "Configurei os paths, mas ao executar a aplicação, recebo o erro 'Cannot find module'". O motivo é simples: TypeScript é um transpilador, não um bundler.

Quando você executa tsc, ele gera arquivos JS, mas mantém os aliases intactos. Por exemplo, import { foo } from '@utils/bar' permanece no JS como está. O Node.js (ou o navegador) não faz ideia do que é @utils e exibe um erro.

Para corrigir isso, você precisa usar uma das seguintes soluções:

\n
• tsc-alias — utilitário que substitui os aliases pelos caminhos reais após a compilação.
\n
• module-alias — pacote npm para registrar aliases no Node.js.
\n