<img src="https://github.com/cat-milk/Anime-Girls-Holding-Programming-Books/blob/master/Typescript/Chito_Saving_Burning_Mastering_Typescript.png?raw=true" alt="">
Tenho usado <a href="https://www.typescriptlang.org/">TypeScript</a> há mais de três anos e, no geral, tem sido uma ótima experiência. Com o tempo, o atrito no uso foi diminuindo até chegar a zero, tornando-me muito mais produtivo ao escrever tipos ou mesmo ao abordar problemas com uma perspectiva orientada a tipos. Embora eu esteja longe de ser um verdadeiro mago dos tipos, ouso me considerar proficiente na linguagem, tendo passado por diversas ginásticas de tipos, tipos condicionais, genéricos aninhados e contemplando a sagrada diferença entre <code>type</code> e <code>interface</code>. Sinceramente, pensei que entendia a linguagem muito bem.
Até que percebi que não. Veja, há uma coisa em particular sobre TypeScript que eu entendi completamente errado, e acredito que você também. E não é algum caso extremo que você nunca ouviu falar e provavelmente nunca usará. Muito pelo contrário. É algo com o qual você, e qualquer outro desenvolvedor TypeScript, interagiu diretamente centenas de vezes, algo que esteve bem debaixo do nosso nariz o tempo todo.
Estou falando sobre o <code>tsconfig.json</code>.
E não, isso não é sobre como ele pode se tornar complexo (confesso que não consigo explicar <code>target</code> e <code>module</code> sem pensar um pouco). Em vez disso, é algo bastante simples. É sobre o que o <code>tsconfig.json</code> realmente faz.
&quot;Bem, é um arquivo de configuração, ele configura o TypeScript, duh.&quot; Certo! Ele faz isso, mas não da maneira que você esperaria. Deixe-me mostrar para você.
<h2>Bibliotecas, testes e a verdade</h2>
Há um grande exemplo por trás de cada grande descoberta. Vou fazer o meu melhor para que este seja ambos.
Vamos escrever uma aplicação frontend simples. E quero dizer realmente simples, sem frameworks, sem dependências. <code>Simples</code>.
<pre><code class="language-typescript">// src/app.ts
const greetingText = document.createElement(&#39;p&#39;)
greetingText.innerText = &#39;Hello, John!&#39;

document.body.appendChild(greetingText)
</code></pre>
Crie um elemento de parágrafo e cumprimente o John. Simples. Até agora, tudo bem.
Mas de onde vem o <code>document</code>? Você pode dizer que é uma variável global em JavaScript e, por todos os meios, você estaria certo. Só tem uma coisa. Nós não estamos em JavaScript. Ainda não, de fato. Estamos olhando para algum código TypeScript no nosso IDE. Ele teria que ser compilado para se tornar JavaScript, ir para o navegador, e para o navegador expor o <code>document</code> globalmente. Então, como o TypeScript conhece o <code>document</code>, sua presença e seus métodos?
O TypeScript faz isso carregando uma biblioteca de definição padrão chamada <code>lib.dom</code>. Pense nela como um arquivo <code>.d.ts</code> contendo vários tipos para descrever os globais do JavaScript, porque é exatamente isso que ela é. Você pode ver isso por si mesmo segurando Ctrl (CMD no Mac) e clicando no objeto <code>document</code>. Mistério resolvido.
Como nossa aplicação é, naturalmente, a melhor coisa desde o pão fatiado, vamos adicionar alguns testes automatizados para ela. Para este passo, vamos trair nossa noção de simplicidade e instalar um framework de testes chamado Vitest. Em seguida, escrevemos o próprio teste:
<pre><code class="language-typescript">// src/app.test.ts
it(&#39;greets John&#39;, async () =&gt; {
 await import(&#39;./app&#39;)
 const greetingText = document.querySelector(&#39;p&#39;)
 expect(greetingText).toHaveText(&#39;Hello, John!&#39;)
})
</code></pre>
Quando tentarmos executar este teste, o TypeScript interferiria com um erro:
<pre><code class="language-typescript">Cannot find name &#39;it&#39;. Do you need to install type definitions for a test runner?
</code></pre>
Dói admitir, mas o compilador tem razão. De onde <code>it</code> viria? Não é um global como <code>document</code>, tem que vir de algum lugar. Bem, na verdade, é bastante comum para os frameworks de teste estenderem o objeto global e exporem funções como <code>it</code> e <code>expect</code> globalmente para que você possa acessá-las em cada teste sem precisar importá-las explicitamente.
Seguimos uma seção convenientemente presente na documentação do nosso framework de testes e habilitamos o <code>it</code> global modificando o <code>tsconfig.json</code>:
<pre><code class="language-typescript">// tsconfig.json
{
 &quot;compilerOptions&quot;: {
 &quot;types&quot;: [&quot;vitest/globals&quot;]
 },
 &quot;include&quot;: [&quot;src&quot;]
}
</code></pre>
Usando <code>compilerOptions.types</code>, estamos pedindo ao TypeScript para carregar tipos adicionais, neste caso de <code>vitest/globals</code>, que declaram a função global <code>it</code>. O compilador sorri para nossos esforços e deixa o teste passar, fazendo-nos sentir particularmente bem sobre nós mesmos e toda essa questão das linguagens estritamente tipadas.
Mas não. Tão. Rápido.
<h2>O Problema</h2>
Vamos dar um pequeno passo ao lado, mas prometo que tudo fará sentido no final.
Deixe-me perguntar: O que acontece se você referenciar um código inexistente no TypeScript? Isso mesmo, uma linha vermelha ondulada e o erro <code>Cannot find name</code>, é o que acontece. Acabamos de ver isso ao tentar chamar <code>it()</code> em um teste.
Volte para o módulo <code>app.ts</code> e adicione uma referência a uma variável global inexistente chamada <code>test</code>:
<pre><code class="language-typescript">// src/app.ts
// ...application code.

test
</code></pre>
Não definimos <code>test</code>. Não é um global do navegador e certamente não existe em nenhuma das bibliotecas padrão do TypeScript. É um erro, um bug, deveria ficar vermelho.
Só que não fica. Como a linha vermelha ondulada não aparece sob o código, um poder percorre você. <del>Autoridade</del>. Confusão. Para piorar as coisas, não só o TypeScript não produz um erro aqui, mas ele realmente tenta ser útil, sugerindo que você tipifique <code>test</code>, mostrando sua assinatura de chamada e dizendo que vem de algum namespace <code>TestApi</code>. Mas isso é um tipo do Vitest, como isso é possível...
Este código compilaria? Claro. Funcionaria no navegador? Não. Ele lançaria um erro como um arremessador experiente em seu dia mais brilhante. Como pode? Não é o propósito inteiro de usar TypeScript evitar erros como este?
O <code>test</code> aqui é o que eu chamo de uma definição fantasma. É uma definição de tipo válida que descreve algo que simplesmente não existe. Mais uma travessura do TypeScript, você diria. Não se apresse em culpar a ferramenta, eu digo. Aqui está o que está acontecendo.
<h2>(Mais de) uma configuração para governar todas</h2>
Mova o módulo de teste <code>app.test.ts</code> do diretório <code>src</code> para um novo diretório chamado <code>test</code>. Abra-o. Espere, isso é um erro de tipo em <code>it</code> de novo? Nós não consertamos isso já adicionando <code>vitest/globals</code> ao nosso <code>tsconfig.json</code>?
A questão é que o TypeScript não sabe o que fazer com o diretório <code>test</code>. Na verdade, o TypeScript nem sabe que ele existe, já que tudo o que apontamos em <code>tsconfig.json</code> é <code>src</code>:
<pre><code class="language-typescript">// tsconfig.json
{
 &quot;compilerOptions&quot;: {
 &quot;types&quot;: [&quot;vitest/globals&quot;]
 },
 &quot;include&quot;: [&quot;src&quot;]
}
</code></pre>
Como mencionei antes, a forma como a configuração do TypeScript funciona não é totalmente óbvia (pelo menos para mim). Por muito tempo eu pensei que a opção <code>include</code> representava quais módulos incluir na compilação, e <code>exclude</code>, respectivamente, controla quais módulos excluir. Se consultarmos a <a href="https://www.typescriptlang.org/tsconfig#include">documentação do TypeScript</a> sobre o assunto, leremos isso:
<code>include</code>, especifica um array de nomes de arquivos ou padrões para incluir no programa.
A forma como passei a entender o que <code>include</code> faz é ligeiramente diferente e mais específica do que o que está declarado na documentação.
<blockquote>
<h1>A opção include controla a quais módulos aplicar esta configuração do TypeScript.</h1>
</blockquote>
Você leu certo. Se um módulo TypeScript está localizado fora dos diretórios listados na opção <code>include</code>, aquele <code>tsconfig.json</code> não terá efeito nenhum sobre aquele módulo. Respectivamente, a opção exclude permite filtrar quais padrões de arquivo não devem ser afetados pela configuração atual.
Ok, então adicionamos <code>test</code> ao <code>include</code> e seguimos com nosso dia, qual é o grande problema?
<pre><code class="language-typescript">// tsconfig.json
{
 &quot;compilerOptions&quot;: {
 &quot;types&quot;: [&quot;vitest/globals&quot;]
 },
 &quot;include&quot;: [&quot;src&quot;, &quot;test&quot;]
}
</code></pre>
Onde a maioria dos desenvolvedores erram. Adicionar novos diretórios ao <code>include</code> expande essa configuração para afetar todos eles. Embora essa mudança resolva os tipos do framework de teste em <code>test</code>, ela vazará para todos os módulos <code>src</code>! 
Você acabou de transformar todo o seu código-fonte em uma mansão assombrada, liberando centenas de tipos fantasmagóricos. Coisas que não existem serão tipificadas, coisas tipificadas podem entrar em conflito com outras definições, e a experiência geral com TypeScript se degradará drasticamente, especialmente à medida que sua aplicação crescer ao longo do tempo.
Então, qual é a solução? Devemos criar vários <code>tsconfig.json</code> para cada diretório? 
Na verdade, sim, você deve. Mas não para cada diretório, e sim para cada ambiente onde seu código deve ser executado.
<h2>Runtimes e preocupações</h2>
Por trás dos bastidores de uma aplicação web moderna há uma mistura de módulos. O código-fonte imediato da sua aplicação deve ser compilado, minificado, dividido em códigos, agrupado e enviado para seus usuários. Existem também arquivos de teste, que são módulos TypeScript também, nunca para serem compilados ou enviados para ninguém. Pode haver também histórias do Storybook, testes do Playwright, talvez um script customizado <code>*.ts</code> ou dois para automatizar coisas—todos úteis, todos com intenções diferentes e destinados a rodar em ambientes diferentes.
Mas para que escrevemos nossos módulos importa. Isso também importa para o TypeScript. Por que você acha que ele fornece o tipo Document por padrão? Porque ele sabe que você provavelmente está desenvolvendo uma aplicação web. Desenvolvendo um servidor Node.js? Seja gentil e declare essa intenção instalando <code>@types/node</code>. O compilador não pode adivinhar por você, você precisa dizer a ele o que deseja.
E você comunica essa intenção através do <code>tsconfig.json</code>. Mas não apenas o de nível raiz. O TypeScript pode lidar muito bem com configurações aninhadas. Porque ele foi projetado para isso. Tudo o que você precisa fazer é ser explícito sobre suas intenções.
<pre><code class="language-typescript"># The root-level configuration to apply TypeScript
# across the entire project. This mostly contains only references.
- tsconfig.json

# The base configuration that all the other configurations
# extend upon. Describe the shared options here.
- tsconfig.base.json

# The source files configuration.
- tsconfig.src.json

# The build configuration.
- tsconfig.build.json

# Configuratin for integration tests.
- tsconfig.test.json

# Configuration for end-to-end tests.
- tsconfig.e2e.test.json
</code></pre>
Woah, isso é muita configuração! Bem, isso também são muitas intenções: desde os arquivos-fonte até vários níveis de testes até a build de produção. Tudo destinado a ser seguro em termos de tipo. E você os torna seguros usando a propriedade <a href="https://www.typescriptlang.org/docs/handbook/project-references.html"><code>references</code></a> da configuração do TypeScript!
A mágica começa no <code>tsconfig.json</code> de nível raiz. Fique tranquilo, esta é a única configuração que o TypeScript irá captar. Todas as outras configurações se tornam referências da configuração de nível raiz, aplicando-se apenas aos arquivos que correspondem ao seu <code>include</code>.
Isso é como um tsconfig.json de nível raiz se parece:
<pre><code class="language-typescript">// tsconfig.json
{
 &quot;references&quot;: [
 // Source files (e.g. everything under &quot;./src&quot;).
 { &quot;path&quot;: &quot;./tsconfig.src.json&quot; },
 // Integration tests (e.g. everything under &quot;./tests&quot;).
 { &quot;path&quot;: &quot;./tsconfig.test.json&quot; },
 // E2E tests (e.g. everything under &quot;./e2e&quot;).
 { &quot;path&quot;: &quot;./tsconfig.e2e.test.json&quot; }
 ]
}
</code></pre>
Como você está usando o campo <code>references</code>, todas as configurações referenciadas devem definir <code>compilerOptions.composite</code> como <code>true</code>. Aqui está um exemplo de <code>tsconfig.src.json</code> para os arquivos-fonte:
<pre><code class="language-typescript">// tsconfig.src.json
{
 // Inherit the reused options.
 &quot;extends&quot;: &quot;./tsconfig.json&quot;,
 // Apply this configuration only to the files
 // under the &quot;./src&quot; directory.
 &quot;include&quot;: [&quot;./src&quot;],
 &quot;compilerOptions&quot;: {
 &quot;composite&quot;: true,
 &quot;target&quot;: &quot;es2015&quot;,
 &quot;module&quot;: &quot;esnext&quot;,
 // Support JSX for React applications.
 &quot;jsx&quot;: &quot;react&quot;
 }
}
</code></pre>
<blockquote>
Você usa uma configuração separada para os arquivos-fonte e para a build porque configurações com <code>compilerOptions.composite</code> não podem ser executadas diretamente. Você aponta o <code>tsc</code> para o específico <code>-p tsconfig.build.json</code> para builds.
</blockquote>
Fica um pouco mais complicado para configurações que se cruzam, como aquela para testes de integração, que deve se aplicar apenas aos arquivos em <code>./tests</code> enquanto ainda permite importar o código-fonte testado. E para isso você utiliza mais uma vez a propriedade de <code>references</code>!
<pre><code class="language-typescript">// tsconfig.test.json
{
 &quot;extends&quot;: &quot;./tsconfig.json&quot;,
 &quot;include&quot;: [&quot;./tests&quot;],
 &quot;references&quot;: [{ &quot;path&quot;: &quot;./tsconfig.src.json&quot; }],
 &quot;compilerOptions&quot;: {
 &quot;composite&quot;: true,
 &quot;target&quot;: &quot;esnext&quot;,
 &quot;module&quot;: &quot;esnext&quot;,
 // Include test-specific types.
 &quot;types&quot;: [&quot;@types/node&quot;, &quot;vitest/globals&quot;]
 }
}
</code></pre>
<h3>A propriedade references diz ao TypeScript para incluir a configuração dada na verificação de tipo, sem permitir que a configuração atual afete os arquivos incluídos.</h3>
<h2>include vs references</h2>
Ambas as propriedades <code>include</code> e <code>references</code> envolvem os arquivos &quot;visíveis&quot; para o TypeScript, mas o fazem de maneiras diferentes. Vamos recapitular essa diferença:
<ul>
<li><code>include</code> controla quais arquivos são afetados por esta configuração.</li>
<li><code>references</code> controla quais arquivos são visíveis para esta configuração, mas não são afetados por ela.</li>
</ul>
A configuração de teste de integração (<code>tsconfig.test.json</code>) ilustra essa diferença perfeitamente. Você deseja que essa configuração se aplique apenas aos arquivos de teste no diretório <code>./tests</code>, então é isso que você fornece em <code>include</code>. Mas você também quer ser capaz de importar o código-fonte testado nesses arquivos, o que significa que o TypeScript precisa conhecer esse código. Você referencia a configuração dos arquivos-fonte (<code>tsconfig.src.json</code>) em <code>references</code>, o que expande transitivamente a visão do TypeScript para os arquivos incluídos lá, sem afetá-los pela configuração dos testes de integração.
<h2>A parte prática</h2>
Para melhor ou pior, estamos nos movendo para uma era onde as ferramentas de desenvolvimento são abstraídas de nós. É justo esperar que seu framework de escolha lide com essa selva de configurações para você. Na verdade, alguns frameworks já fazem isso. Tome o <a href="https://github.com/vitejs/vite/tree/1c031723a821d654e9aed44e43a0a5fa47c240da/packages/create-vite/template-react-ts">Vite</a> como exemplo. Estou bastante confiante de que você pode encontrar uma configuração multi-configuração para TypeScript em praticamente qualquer outro projeto.
Mas eu quero que você entenda que o TypeScript ainda é sua ferramenta, abstraída ou não, e você faria bem em aprender mais sobre ela, entendê-la melhor e usá-la corretamente.

Uma Coisa Que Nunca Te Explicaram Sobre TypeScript

Typescript

Fique atualizado!