Se você já enviou um bugfix de duas linhas para um monorepo TypeScript e assistiu seu pipeline de build devorar dez minutos de checagem de tipos, você já entende o problema. O atraso não é o bundling. Não é a minificação. É o momento em que o TypeScript tenta escrever seus arquivos de declaração. Antes de emitir um único arquivo .d.ts, o compilador deve resolver o grafo de tipos completo. Ele percorre imports, avalia genéricos e infere tipos de retorno que podem estar três camadas de dependência abaixo. Aquele arquivo que você alterou toca outro arquivo, que toca um terceiro, e de repente o compilador está realizando um trabalho de detetive em todo o repositório apenas para descrever o que sua função retorna.

O TypeScript 6.0 introduz o isolatedDeclarations para quebrar esse hábito.

O Verdadeiro Gargalo

Arquivos de declaração são o contrato público do seu código. Quando outro desenvolvedor importa seu pacote, o TypeScript lê os arquivos .d.ts, não o código-fonte. Gerar esses arquivos corretamente significa que o compilador não pode pular a checagem de tipos. Ele deve conhecer cada formato, cada união e cada tipo de retorno inferido antes de escrever uma única linha de saída.

Em um projeto pequeno com cinquenta arquivos, isso é instantâneo. Em um monorepo grande com milhares de módulos, é um pesadelo serializado. Altere um tipo utilitário em um pacote core e o compilador revisitará cada consumidor para verificar se os tipos inferidos ainda se mantêm. O tempo de build escala com a profundidade da dependência, não apenas com a contagem de arquivos. Um refactor trivial pode disparar uma recomputação de todo o grafo. As equipes costumam aceitar isso como inevitável. Não é.

Como o isolatedDeclarations Funciona

A nova flag altera o contrato entre você e o compilador. Em vez de pedir ao TypeScript para inferir os tipos de seus exports, você mesmo os anota. Essa única mudança remove a necessidade de conhecimento global. O compilador não precisa mais analisar suas dependências para emitir declarações para o seu módulo. Ele olha apenas para a sintaxe à sua frente.

Isso significa que cada arquivo pode emitir sua saída .d.ts de forma independente, em paralelo. A ferramenta de build não precisa construir um grafo de tipos completo antes de iniciar a geração de declarações. Ferramentas como esbuild e swc, que anteriormente evitavam a emissão de .d.ts por não possuírem um verificador de tipos, agora podem gerar declarações em velocidades próximas à transpilação. Elas leem as anotações explícitas diretamente da fonte e escrevem as definições de tipo correspondentes sem resolver nenhuma equação de tipo.

Anteriormente, a emissão de declarações era um monopólio do tsc, pois apenas o compilador oficial possuía as informações de tipo necessárias para produzir arquivos .d.ts. Transpiladores rápidos podiam remover tipos ou converter sintaxe, mas não podiam gerar definições de tipo. Com o isolatedDeclarations, abre-se as portas para que todo o ecossistema lide com fluxos de trabalho de declaração. A transformação torna-se mecânica em vez de lógica. Essa distinção é o que transforma uma espera de dez minutos em segundos.

O Tradeoff: Explícito é o Novo Padrão

A velocidade vem com um preço direto. Cada função, classe e variável exportada deve conter uma anotação de tipo explícita. O TypeScript se recusará a inferir a API pública para você.

Considere um utilitário simples:

export function getUser(id: number) {
  return fetchUser(id);
}

Com o isolatedDeclarations habilitado, isso resultará em erro. O compilador não pode saber o tipo de retorno de fetchUser sem inspecioná-lo, e sob esta flag