Tecnologias/01 - Linguagens/02 - TypeScript2 min

Módulos e Configuração do TypeScript

Módulos

Módulos delimitam o que um arquivo expõe e quais dependências ele usa. No formato ESM, export publica declarações e import as consome. CommonJS usa mecanismos como require e module.exports. O ambiente de execução ou a ferramenta de build precisa entender o formato produzido.

// contrato.ts
export interface Produto {
  id: string;
  preco: number;
}

// resumo.ts — exemplo de ESM compilado para JavaScript
import type { Produto } from "./contrato.js";

export function resumo(produto: Produto): string {
  return `${produto.id}: ${produto.preco}`;
}

import type importa apenas informação de tipos e é removido da saída. A extensão .js neste exemplo corresponde ao arquivo emitido para execução; a resolução do TypeScript pode associá-lo ao fonte .ts. Referência: teoria de módulos.

tsconfig.json

O arquivo configura a verificação, a seleção de arquivos e a emissão de código.

Opção	Papel
`strict`	Ativa um conjunto de verificações mais rigorosas
`target`	Define o nível de sintaxe JavaScript usado na emissão
`module`	Define o comportamento e formato de módulos
`moduleResolution`	Define como localizar módulos importados
`noEmit`	Verifica sem produzir arquivos JavaScript
`noEmitOnError`	Impede emissão quando há erros reportados
`lib`	Seleciona declarações de APIs que o compilador considera disponíveis

lib não instala APIs no ambiente. target também não fornece automaticamente polyfills. O código pode passar na verificação e chamar uma API ausente no runtime. Referência: TSConfig.

Declarações e dependências

Arquivos .d.ts descrevem APIs para o compilador. A implementação real da biblioteca precisa existir separadamente. Uma declaração não garante que a versão instalada se comporte de acordo com o contrato.

A configuração de módulos deve corresponder ao ambiente: um projeto executado por Node e outro empacotado para navegador podem precisar de configurações diferentes.

Aprofundamento aplicado

Três perguntas para diagnosticar um import

O compilador localiza o código ou apenas uma declaração .d.ts?
Qual caminho e formato aparecem no JavaScript emitido?
O ambiente que executa esse JavaScript consegue resolver esse caminho?

Um alias @dominio/cliente pode funcionar no editor e falhar em produção se somente o TypeScript conhecer seu mapeamento. Configurar a resolução estática não instala um resolvedor no Node nem reescreve necessariamente os imports emitidos. Referência: módulos e host.

Configuração como contrato de execução

Situação	Verificação necessária
Bundler produz o artefato	O bundler entende imports, aliases e extensões usados
Node executa arquivos emitidos	Formato de módulos, extensões e `package.json` concordam
Biblioteca publicada	Entradas de runtime e declarações apontam para arquivos existentes
`noEmit` no projeto	Outra etapa realmente produz ou executa o código

Exercício: compile dois módulos e execute a saída fora do editor, a partir de um diretório limpo. Resultado esperado: nenhum import depende de arquivos-fonte que ficaram fora do artefato. Esse teste revela diferenças entre a experiência no editor e o pacote que será distribuído.

Relacionado: 1. TypeScript · 8. Validação de Dados em TypeScript.