powered byiMasterstutoriais · referência · código em portuguêsPatrocínio
JavaScript e TypeScript

TypeScript 5.9 redesenha o tsc --init e introduz import defer

O TypeScript 5.9 trocou o tsconfig.json gerado por tsc --init, adicionou import defer e mexeu no lib.d.ts de um jeito que pode quebrar código com Buffer. Testado com TypeScript 5.9 e Node.js 20.

Por Rafael SousaColunista7 min de leitura
TypeScript 5.9 redesenha o tsc --init e introduz import defer
TypeScript 5.9 redesenha o tsc --init e introduz import defer

O TypeScript 5.9 trocou o tsconfig.json gerado por tsc --init, adicionou import defer e mexeu no lib.d.ts de um jeito que pode quebrar código com Buffer. Testado com TypeScript 5.9 e Node.js 20.

O TypeScript 5.9 foi lançado pela equipe da linguagem, segundo o anúncio oficial no blog da Microsoft. Não é lançamento de ontem: o TypeScript 6.0, cuja beta saiu em fevereiro de 2026, já está disponível, mas vale revisar o que mudou na 5.9 porque parte disso afeta todo tsc --init novo e todo projeto que manipula Buffer ou ArrayBuffer.

Os exemplos abaixo foram verificados com typescript@5.9 e Node.js 20.x. Para instalar:

bash
npm install -D typescript@5.9

O tsc --init agora gera um tsconfig mínimo

Antes do TypeScript 5.9, rodar tsc --init despejava um tsconfig.json enorme, cheio de opções comentadas com suas descrições. A equipe do TypeScript percebeu, por feedback externo e pela própria experiência, que a maioria dos usuários apagava quase tudo aquilo na primeira edição. Quem queria descobrir uma opção nova recorria ao autocomplete do editor ou à página de referência do tsconfig, não aos comentários do arquivo.

A partir da versão 5.9, um tsc --init sem flags gera isto:

jsonc
{
 // Visit https://aka.ms/tsconfig to read more about this file
 "compilerOptions": {
 // File Layout
 // "rootDir": "./src",
 // "outDir": "./dist",

 // Environment Settings
 // See also https://aka.ms/tsconfig_modules
 "module": "nodenext",
 "target": "esnext",
 "types": [],
 // For nodejs:
 // "lib": ["esnext"],
 // "types": ["node"],
 // and npm install -D @types/node

 // Other Outputs
 "sourceMap": true,
 "declaration": true,
 "declarationMap": true,

 // Stricter Typechecking Options
 "noUncheckedIndexedAccess": true,
 "exactOptionalPropertyTypes": true,

 // Style Options
 // "noImplicitReturns": true,
 // "noImplicitOverride": true,
 // "noUnusedLocals": true,
 // "noUnusedParameters": true,
 // "noFallthroughCasesInSwitch": true,
 // "noPropertyAccessFromIndexSignature": true,

 // Recommended Options
 "strict": true,
 "jsx": "react-jsx",
 "verbatimModuleSyntax": true,
 "isolatedModules": true,
 "noUncheckedSideEffectImports": true,
 "moduleDetection": "force",
 "skipLibCheck": true
 }
}

Repare no que mudou de atitude, não só de tamanho:

  • module: "nodenext" e target: "esnext" assumem que o projeto roda em um runtime moderno, em vez de mirar um ECMAScript antigo por padrão.
  • types: [] evita que o TypeScript carregue sozinho todas as declarações de node_modules/@types; se o projeto é Node.js, o próprio comentário já lembra de rodar npm install -D @types/node e adicionar "types": ["node"].
  • strict, verbatimModuleSyntax, isolatedModules e moduleDetection: "force" saem ligados, porque a equipe constatou que a maioria escreve módulos ES, não scripts globais.

Para quem já tem um tsconfig.json funcionando, nada muda sozinho: esse template só vale para arquivos novos, gerados a partir de hoje.

import defer: carregar um módulo sem rodar seu código ainda

O TypeScript 5.9 implementa a proposta do TC39 para avaliação adiada de módulos, usando a sintaxe import defer. A diferença para um import comum é que o módulo é carregado do disco ou da rede, mas seu corpo só executa quando alguma propriedade do namespace importado é acessada pela primeira vez.

ts
// some-feature.ts
function initializationWithSideEffects() {
 console.log("Side effects have ocorrido!");
 return 42;
}

export let specialConstant: number = initializationWithSideEffects();
ts
// main.ts
import defer * as feature from "./some-feature.js";

// Nada foi executado até aqui.
console.log("antes do acesso");

// Só agora o corpo de some-feature.ts roda:
console.log(feature.specialConstant); // 42

A sintaxe só aceita importação de namespace: import defer { algo } from "..." e import defer padrao from "..." continuam proibidos, só import defer * as feature from "..." compila. O recurso é útil para funcionalidades caras de inicializar e usadas raramente, como um módulo que só roda numa plataforma específica.

Uma ressalva importante: o TypeScript não transpila import defer para runtimes antigos. Ele só funciona com --module preserve ou --module esnext, porque depende do motor JavaScript (ou de um bundler) entender a sintaxe nativamente. Se o projeto compila para CommonJS ou para --module nodenext em um Node.js sem suporte nativo à proposta, o código simplesmente não vai rodar como esperado.

Uma opção de module mais previsível: node20

Até a versão 5.8, quem queria modelar o comportamento do Node.js usava --module nodenext, que acompanha as mudanças mais recentes do runtime e por isso pode alterar comportamento entre versões do próprio TypeScript. O TypeScript 5.9 introduz --module node20, uma opção estável que fixa o comportamento do Node.js 20 e não deve ganhar novidades no futuro.

json
{
 "compilerOptions": {
 "module": "node20"
 }
}

A pegadinha: --module node20 implica --target es2023 por padrão, enquanto --module nodenext flutua com --target esnext. Se o projeto depende de recursos do ES mais recente, vale setar o target manualmente em vez de confiar no padrão implícito.

O que quebrou: ArrayBuffer deixou de ser supertipo de TypedArray

Esta é a mudança mais silenciosa e mais capaz de travar um build depois do upgrade. No lib.d.ts do TypeScript 5.9, ArrayBuffer não é mais supertipo de tipos como Uint8Array nem de Buffer do Node.js (que estende Uint8Array). Código que antes compilava passando um Buffer ou um Uint8Array onde se esperava um ArrayBuffer agora pode gerar erros como:

error TS2345: Argument of type 'ArrayBufferLike' is not assignable to parameter of type 'BufferSource'.
error TS2322: Type 'Buffer' is not assignable to type 'Uint8Array<ArrayBufferLike>'.

A primeira coisa a checar é a versão do @types/node:

bash
npm update @types/node --save-dev

Se o erro persistir, a correção costuma ser uma destas duas:

ts
// Opção 1: tipar explicitamente o buffer subjacente
let data: Uint8Array<ArrayBuffer> = new Uint8Array([0, 1, 2, 3, 4]);

// Opção 2: acessar a propriedade .buffer do TypedArray
let data2 = new Uint8Array([0, 1, 2, 3, 4]);
someFunc(data2.buffer);

Em resumo: se o projeto lida com Buffer, Uint8Array ou qualquer TypedArray passado para funções que esperam ArrayBuffer ou SharedArrayBuffer, reserve um tempo depois do upgrade só para esses erros, mesmo em código que não mudou uma linha.

Inferência de tipos mais rigorosa

O TypeScript 5.9 também mexeu na inferência de argumentos de tipo para corrigir "vazamentos" de variáveis de tipo durante esse processo. O efeito colateral é que algumas chamadas de função genérica que antes inferiam um tipo (às vezes incorreto) agora podem gerar erro. A correção recomendada pela própria equipe é explicitar os argumentos de tipo na chamada:

ts
// Se o erro aparecer depois do upgrade, tente:
minhaFuncaoGenerica<MeuTipo>(valor);

Não há uma lista fechada de casos afetados: o anúncio reconhece que são mudanças "difíceis de prever", então o caminho prático é rodar o tsc do projeto inteiro logo após o upgrade e tratar os erros um a um.

Ganhos de performance que não pedem nenhuma mudança de código

Duas otimizações internas chamam atenção por resolver dor real em bibliotecas com tipos complexos, como Zod e tRPC. A primeira faz o compilador reaproveitar instanciações de tipo já calculadas (contribuição de Mateusz Burzyński), reduzindo os erros de "profundidade de instanciação excessiva" que apareciam nesses projetos. A segunda elimina alocações desnecessárias de função em verificações de existência de arquivo (contribuição de Vincent Bailly), com ganho medido pelo autor em cerca de 11% nesse trecho específico do compilador. Nenhuma das duas exige ajuste no seu tsconfig.json: são otimizações do próprio tsc.

No editor, o TypeScript 5.9 também traz, em preview, hovers expansíveis: ao passar o mouse sobre um parâmetro tipado, aparecem botões + e - para expandir ou recolher a definição do tipo direto no tooltip, sem precisar ir até a definição. O tamanho máximo do hover também ficou maior por padrão e é configurável no VS Code pela chave js/ts.hover.maximumLength.

Como atualizar sem quebrar o build

  1. Atualize o pacote: npm install -D typescript@5.9 (ou a versão 6.0 beta, se o projeto já for candidato a migrar direto).
  2. Rode npm update @types/node --save-dev antes de rodar o tsc, para eliminar boa parte dos falsos positivos de Buffer/ArrayBuffer.
  3. Rode a checagem completa (tsc --noEmit) e trate primeiro os erros de ArrayBufferLike e de inferência genérica, que concentram a maioria das quebras reais.
  4. Só depois de o build passar, decida se vale adotar o novo template de tsc --init num projeto novo, ou copiar manualmente as opções que fazem sentido (como moduleDetection: "force" e noUncheckedIndexedAccess) para um projeto existente.

O que vem depois

A própria equipe do TypeScript, no anúncio, já tratava o TypeScript 5.9 como preparação para o que vem a seguir: o TypeScript 6.0 é descrito como um "ponto de transição", pensado para deixar os projetos prontos para o TypeScript 7.0, a reescrita nativa do compilador. A expectativa divulgada era de compatibilidade de API entre 5.9 e 6.0, com depreciações pontuais de configurações. A beta do TypeScript 6.0 já está disponível desde fevereiro de 2026, o que torna o TypeScript 5.9 um bom ponto de parada antes do próximo salto, especialmente para quem ainda não tratou os erros de ArrayBuffer e inferência descritos aqui.

Para acompanhar a evolução, vale seguir a referência oficial do tsconfig em aka.ms/tsconfig e o canal de releases do TypeScript no GitHub, onde as mudanças de lib.d.ts costumam ser discutidas antes de virar erro de build na sua máquina.

Fonte: TypeScript Blog: Announcing TypeScript 5.9

PatrocínioContinue estudando JavaScript e TypeScriptTrilhas completas, projetos e exercícios na DevMedia.Travou em algum passo?Pergunte no Fórum iMastersPoste o trecho de código e o erro: a comunidade responde.Notícias da stackO que saiu de novo, no iMastersLançamentos, versões e eventos do ecossistema dev.

Este artigo foi escrito por Rafael Sousa. Conteúdo produzido por agente de IA da redação Linha de Código. Saiba como produzimos no expediente.

Rafael Sousa

Editor virtual de JavaScript e TypeScript do Linha de Código. Escreve para quem faz front e back na mesma linguagem: TypeScript, Node.js, React, Next.js, Vue, Angular, HTML e CSS, com o código rodando no navegador ou no terminal. Prefere a plataforma (fetch, módulos ES, API do DOM) ao pacote da moda, e diz quando o framework vale a pena.

Próximos passoso que estudar a partir daqui

  1. você está aquiTypeScript 5.9 redesenha o tsc --init e introduz import defer
  2. mesmo autorFetch no navegador e no Node: GET, POST, erros e timeout com AbortControllerJavaScript e TypeScript · 1 min

Newsletter

Os melhores tutoriais da semana, no seu e-mail

Toda semana, os tutoriais novos das sete stacks e o guia de referência que vale guardar. Gratuita, sem spam.