Configuração, entrega e migração

target e lib respondem a perguntas diferentes

target controla a sintaxe JavaScript que o compilador mantém ou transforma durante a emissão. lib seleciona conjuntos de declarações para a verificação. Acrescentar DOM pode tornar document conhecido pelo compilador, mas não cria um DOM no processo. Do mesmo modo, declarar uma API recente não instala a respetiva implementação nem um polyfill.

Escolhe ambos a partir do host suportado e da estratégia de entrega. No exemplo, ES2022 identifica uma base de linguagem e declarações; não é uma promessa sobre qualquer servidor existente. Se a aplicação usa APIs específicas de Node ou do browser, essas dependências precisam de tipos e implementações adequados, para além da configuração ilustrada.

Configuração de módulos tem de representar o destino

module e moduleResolution participam no modelo de módulos e na forma de resolver imports. O exemplo assume nodenext e um package.json com type: module. verbatimModuleSyntax torna explícita a distinção entre imports apagados por serem de tipos e imports de valores mantidos neste contexto ESM.

Se os ficheiros forem interpretados como CommonJS, este modo não converte silenciosamente a sintaxe ESM em chamadas require. O diagnóstico deve levar à revisão do formato e da configuração, não a desligar opções até o erro desaparecer. Uma configuração que aceita os ficheiros só é útil se representar o ambiente onde os artefactos serão consumidos.

Verificar e emitir podem ser etapas distintas

noEmit permite usar o compilador para verificar sem produzir os seus ficheiros de saída. É útil quando outra ferramenta gera o JavaScript, mas não garante que essa ferramenta verifique os tipos. O pipeline precisa de exigir o resultado da verificação antes de aceitar o artefacto transformado da mesma revisão.

noEmitOnError tem outra finalidade: impedir nova emissão quando a compilação contém erros. A opção não apaga resultados de execuções anteriores. Encontrar dist depois de uma falha não demonstra que a revisão atual produziu conteúdo aceitável. Identifica a origem do artefacto e usa saídas isoladas ou limpeza controlada para evitar confusão entre execuções.

Migrar JavaScript sem fingir que tudo já está coberto

allowJs permite incluir ficheiros JavaScript no projeto de TypeScript, apoiando uma transição gradual. checkJs acrescenta diagnósticos aos ficheiros JavaScript incluídos. Incluir e verificar são decisões relacionadas, mas distintas; uma equipa deve registar que ficheiros e configurações fazem parte de cada etapa.

Começa por fronteiras úteis, como funções exportadas e dados recebidos, conservando o comportamento exigido enquanto aumentas a informação de tipos. Acrescentar any a todas as chamadas pode reduzir diagnósticos sem aumentar confiança. A migração deve explicitar as zonas ainda pouco descritas e evitar tratar a extensão .ts como prova suficiente de qualidade.

O alcance de skipLibCheck deve ficar visível

skipLibCheck omite a verificação dos ficheiros de declaração. Pode reduzir trabalho de verificação ou contornar temporariamente conflitos, mas não reconcilia versões incompatíveis nem altera as implementações entregues. As utilizações dos tipos no código da aplicação continuam a participar na análise.

Quando a opção é usada por causa de declarações duplicadas, regista a causa e a decisão de resolução. Corrigir a árvore de dependências ou alinhar versões pode eliminar a inconsistência que estava a ser ocultada. Não concluas que o contrato de um pacote é correto apenas porque deixaste de analisar parte das suas declarações.

A CLI e a API são superfícies de integração distintas

A base desta aula é TypeScript 7.0. A publicação dessa versão distingue a CLI nativa da API programática: 7.0 não fornece essa API. Uma ferramenta que importa a API anterior não fica migrada só porque o comando de verificação nativo funciona. A dependência de cada ferramenta deve ser analisada separadamente.

A documentação descreve @typescript/typescript6 e aliases npm para coexistência com a CLI 7.0 quando uma ferramenta ainda precisa da API 6.0. Usa versões explícitas e o mecanismo compatível com o consumidor. Esta coexistência pode ser uma decisão operacional válida, mas deve conservar o registo da migração pendente; uma intenção sobre uma versão futura não prova disponibilidade em 7.0.

Leitura guiada de uma decisão de publicação

Na configuração apresentada, src delimita a origem e dist recebe a saída. strict e noUncheckedIndexedAccess aumentam os diagnósticos em áreas estudadas antes. noEmitOnError impede nova emissão com erros, mas uma decisão de publicação ainda precisa do resultado da execução atual, da revisão analisada e do artefacto que lhe corresponde.

Compara dois registos: um contém apenas “dist existe”; o outro identifica revisão, versão do compilador, configuração, resultado da verificação e conteúdo a publicar. O segundo permite investigar divergências. Fixar dependências e um host suportado também evita atribuir ao código diferenças causadas por uma mudança silenciosa de ferramentas ou por target: ESNext.

Armadilhas comuns

Tratar lib como polyfill; ignorar um tsc falhado porque há ficheiros em dist; ativar skipLibCheck como correção de dependências; confundir compatibilidade da CLI com compatibilidade da API.