tsconfig.json Opções do compilador e modelo de configuração
Última atualização: 2026-10-22
tsconfig.json Opções do compilador e modelo de configuração
tsconfig.json é o interruptor mestre de um projeto TypeScript: colocado na raiz do projeto, diz ao compilador (tsc) quais arquivos compilar e como. strict é a opção mais importante — uma única flag ativa toda a família estrita (strictNullChecks, noImplicitAny, ...), capturando a maioria dos perigos de null e de tipos em tempo de compilação.
| Grupo | Configuração e Prática |
|---|---|
| Tipo | Configuração |
| Modo strict | Não necessário |
ℹ️ Info O editor transpila TypeScript para JavaScript e o executa (sem verificação de tipos); veja a Saída de cada exemplo para o resultado da verificação.
📝 Sintaxe
// tsconfig.json (configuração strict mínima)
{
"compilerOptions": {
"target": "ES2020", // versão da linguagem JS da saída
"module": "commonjs", // formato de módulo (commonjs para Node, ESNext para bundlers)
"outDir": "./dist", // diretório de saída
"rootDir": "./src", // raiz dos fontes
"paths": { "@utils/*": ["./src/utils/*"] }, // apelidos de caminho de módulo
"strict": true // ativa toda a família de verificações strict de uma vez
},
"include": ["src"] // compila apenas os arquivos sob src
}⚙️ Parâmetros
| strict | Interruptor mestre das verificações estritas: ativa strictNullChecks, noImplicitAny, strictFunctionTypes e mais; basta ativá-lo em projetos novos |
|---|---|
| target / module | target escolhe a versão da linguagem do JS de saída (os tipos nativos a acompanham); module escolhe o formato de módulo da saída |
| outDir / rootDir / paths | Diretório de saída / raiz do código-fonte / aliases de caminho. paths é apenas um mapeamento de nomes em tempo de compilação — a resolução em tempo de execução ainda depende de configuração do bundler ou de subpaths do Node |
Retorno：Sem valor de retorno — tsconfig.json é um arquivo de configuração; afeta apenas a compilação e nunca é executado.
▶ Exemplo
Edite o código abaixo e clique em Testar para ver o resultado transpilado:
Saída：
length = 5
sum = 5
(Saída de execução após a transpilação; a verificação de tipos é feita pelo tsc — remover o fallback ?? produz error TS18047, e tirar as anotações de parâmetro de sum produz error TS7006)💡 Observações
ℹ️ Info strict não é uma verificação única, mas um pacote: strictNullChecks, noImplicitAny, strictFunctionTypes, strictBindCallApply, strictPropertyInitialization, useUnknownInCatchVariables e mais.
💡 Dica Inicialize projetos novos com tsc --init e poda o modelo; mantenha os aliases de paths em sincronia com os aliases do seu bundler (Vite/webpack), senão a compilação passa e o tempo de execução não encontra os módulos.
⚠️ Atenção Bases de código legadas não precisam adotar strict de uma vez: ative primeiro apenas strictNullChecks, corrija gradualmente e depois ligue o strict completo quando a árvore estiver limpa.
🏷️ Configuração e Prática Relacionadas
💡 Casos relacionados
Mais casos em breve.
📚 Tutoriais relacionados
❓ Perguntas frequentes
P O que exatamente strict: true ativa?
R Ele reúne várias verificações: strictNullChecks (tratamento explícito de null/undefined), noImplicitAny (sem any implícito), strictFunctionTypes (parâmetros de função contravariantes), strictPropertyInitialization (campos de classe precisam ser inicializados), useUnknownInCatchVariables (variáveis de catch são unknown) etc. É possível desativar itens individuais para uma migração gradual.
P Qual é a diferença entre target e module?
R target controla o rebaixamento da sintaxe para uma versão do JS (ES2020 suporta encadeamento opcional); module controla o sistema de módulos emitido (commonjs / ESNext / node16). target governa recursos da linguagem; module governa como import/export é emitido.
P Configurei aliases de paths, mas o tempo de execução não encontra os módulos — por quê?
R paths é um mapeamento de nomes apenas para o compilador; o código emitido mantém o alias intacto. O tempo de execução também precisa conhecê-lo: configure o resolve.alias do Vite/webpack em projetos com bundler, ou use o campo imports do package.json (ou um patch em tempo de execução como tsconfig-paths) para Node puro.
