Declarações Isoladas no TypeScript: Aumente a Velocidade do Monorepo
Builds de monorepos costumam ficar lentos devido à forma como o TypeScript lida com arquivos de declaração. Por padrão, o TypeScript analisa cada cadeia de importação antes de criar um único arquivo .d.ts. Isso cria uma fila longa onde os pacotes precisam esperar uns pelos outros.
Você pode corrigir isso com a flag --isolatedDeclarations.
Esta flag permite builds paralelos. Em vez de esperar pelas dependências, cada pacote gera suas próprias declarações de forma independente. Equipes observam um aumento na velocidade de build de 3x a 15x.
O Problema: O TypeScript geralmente infere tipos através das fronteiras dos módulos. Se o Pacote A depende do Pacote B, o compilador deve resolver completamente o B antes de poder começar o A. Em um monorepo grande, a maioria dos pacotes fica ociosa enquanto o compilador trabalha um por um.
A Solução:
A flag --isolatedDeclarations muda as regras. Ela exige que você escreva anotações de tipo explícitas para tudo o que você exportar.
O Tradeoff: Seu código terá mais texto. Você deve adicionar manualmente tipos de retorno a funções e tipos a constantes. Você não pode contar com o compilador para adivinhar esses tipos a partir do seu código.
O Resultado: Como cada exportação possui um tipo claro, o compilador não precisa olhar para outros pacotes para entendê-las. Ele pode processar cada pacote ao mesmo tempo.
Resultados no Mundo Real:
- Um monorepo com 18 pacotes reduziu o tempo de build de 47 segundos para 3,2 segundos.
- Um monorepo de 32 pacotes teve ganhos de 8x em pipelines de CI.
- O desempenho escala com os núcleos da sua CPU. Mais núcleos significam que mais pacotes são compilados de uma só vez.
Como Migrar:
- Ative a flag no seu
tsconfig.jsonraiz e em cada configuração de pacote. - Use a flag
"composite"para permitir referências de projeto. - Adicione tipos de retorno explícitos às funções exportadas:
// Antes export function add(a: number, b: number) { return a + b; }
// Depois export function add(a: number, b: number): number { return a + b; }
- Adicione tipos explícitos às constantes exportadas:
// Antes export const SETTINGS = { port: 3000 };
// Depois export const SETTINGS: { port: number } = { port: 3000 };
Se você não adicionar esses tipos, o compilador lançará erros. Isso garante que seus tipos sejam determinísticos e rápidos.