Como instalar e configurar TypeScript no projeto

Para instalar TypeScript de forma previsível, crie um projeto Node, adicione o pacote typescript como dependência de desenvolvimento, gere um tsconfig.json e rode o compilador local com npx tsc. Ao final desta lição, você terá um arquivo .ts verificado, um .js gerado em dist e um erro de tipo reproduzido no terminal.

Esse é o primeiro passo da trilha de TypeScript. Se o papel do compilador ainda não estiver claro, o guia completo de TypeScript mostra o mapa antes de você mexer nas opções. Aqui a gente fica no caminho executável: instalar, configurar, compilar, quebrar de propósito e corrigir.

A portaria do projeto: o modelo mental da compilação

Pense num prédio comercial. A portaria confere nome, destino e autorização antes de liberar a entrada. Ela não faz o trabalho de cada empresa e não acompanha a pessoa para sempre; aplica regras num ponto de passagem. O compilador TypeScript ocupa esse ponto entre seu código .ts e o JavaScript que será executado.

No mapeamento técnico, o arquivo TypeScript é a pessoa chegando, o tsconfig.json é o conjunto de regras da portaria, o tsc é quem confere e a pasta dist recebe o JavaScript liberado. O limite da analogia: o compilador analisa estruturas de tipo, não intenção de negócio. Um preço negativo pode ser number e ainda estar errado para sua loja.

Guarde o fluxo: escrever → checar → emitir → executar. Em alguns projetos a ferramenta de build emite o JavaScript, e o tsc só checa. Mesmo assim, essas etapas continuam conceitualmente separadas.

Confirme o ambiente antes de instalar

Abra um terminal num diretório vazio e confira as versões. Os exemplos desta lição foram executados com Node 24.16.0, npm 11.13.0 e TypeScript 7.0.2.

node --version
npm --version

Se o terminal disser que node não existe, instale uma versão LTS antes de seguir. Node é o ambiente usado aqui para rodar o JavaScript e npm é o gerenciador que baixa o compilador. A lição o que é Node.js explica essa divisão sem misturar runtime e linguagem.

Agora inicie o projeto e instale TypeScript localmente:

npm init -y
npm install --save-dev typescript@7.0.2
npx tsc --version

--save-dev registra TypeScript em devDependencies: ele participa do desenvolvimento, mas seus tipos não precisam ser enviados para executar o JavaScript em produção. npx procura o comando dentro de node_modules/.bin, portanto usa a versão do projeto em vez de uma instalação global esquecida na máquina. Para entender onde essa versão fica registrada, veja npm e package.json.

Gere o arquivo que concentra as regras

O comando abaixo cria um tsconfig.json inicial:

npx tsc --init

O arquivo gerado traz comentários e várias opções. Para este exercício, deixe-o com uma base curta. JSON normal não aceita comentários; o TypeScript lê JSONC no tsconfig, mas manter o exemplo limpo ajuda a enxergar cada decisão.

{
  "compilerOptions": {
    "target": "ES2024",
    "module": "nodenext",
    "moduleResolution": "nodenext",
    "strict": true,
    "rootDir": "src",
    "outDir": "dist",
    "noUncheckedIndexedAccess": true,
    "sourceMap": true
  },
  "include": ["src/**/*.ts"]
}

target define a versão de JavaScript emitida. module e moduleResolution explicam como imports são gerados e encontrados; nodenext acompanha as regras modernas do Node. strict ativa a família de verificações que dá valor ao projeto. rootDir separa fonte de saída, enquanto outDir evita misturar .ts e .js na mesma pasta. include restringe quais arquivos entram na compilação.

Não trate esse bloco como configuração universal. Um aplicativo criado com Vite ou um framework já traz um tsconfig adaptado ao próprio build. O princípio que permanece é ler as opções do projeto e saber quem checa e quem emite.

Compile a primeira regra de negócio

Crie a pasta src e dentro dela o arquivo src/index.ts:

type Item = {
  nome: string;
  preco: number;
  quantidade: number;
};

function subtotal(item: Item): number {
  return item.preco * item.quantidade;
}

const teclado: Item = {
  nome: 'Teclado',
  preco: 250,
  quantidade: 2,
};

console.log(`${teclado.nome}: R$ ${subtotal(teclado).toFixed(2)}`);

O nome técnico de Item é type alias. Em palavras simples, ele dá um nome ao formato que a função aceita. subtotal exige esse formato e declara que devolve um número. Agora peça ao compilador para checar e emitir:

npx tsc
node dist/index.js

O tsc sem nome de arquivo procura o tsconfig.json do diretório atual. Se a checagem passar, dist/index.js aparece. Abra esse arquivo e procure type Item: ele não está lá. Tipos foram usados na portaria e removidos antes da execução.

Reproduza um erro antes de corrigi-lo

Troque somente o preço do objeto por texto:

const teclado: Item = {
  nome: 'Teclado',
  preco: '250',
  quantidade: 2,
};

Rode a checagem sem gerar uma nova saída:

npx tsc --noEmit

O número da linha varia se você manteve o arquivo completo; a parte estável é TS2322 e a incompatibilidade entre string e number. A mensagem não está pedindo uma conversão automática. Ela diz que o valor atual não cumpre o contrato. Corrija para 250, rode npx tsc --noEmit outra vez e confirme que o terminal fica sem diagnóstico.

Esse silêncio é uma saída observável: o processo termina com código zero. Em um pipeline de integração contínua, código zero libera a próxima etapa; diagnóstico faz o comando terminar com falha e bloqueia uma versão incoerente.

Transforme os comandos em scripts do projeto

Digitar o comando inteiro funciona, mas scripts dão nomes iguais para toda a equipe. Acrescente estas entradas em scripts no package.json criado pelo npm:

{
  "scripts": {
    "typecheck": "tsc --noEmit",
    "build": "tsc",
    "start": "node dist/index.js"
  }
}

Agora o fluxo cabe em três comandos:

npm run typecheck
npm run build
npm start

O npm encontra tsc local automaticamente dentro de scripts. Isso evita que uma pessoa use 7.0.2 e outra compile sem perceber com uma versão global antiga. O arquivo de lock criado na instalação registra a resolução exata das dependências e deixa instalações futuras reproduzíveis.

Quando o editor ajuda e quando o terminal decide

Editores modernos mostram o sublinhado vermelho enquanto você digita. Esse retorno rápido usa o servidor da linguagem TypeScript e é ótimo para corrigir no contexto. Ainda assim, o terminal é a verificação compartilhável: outra máquina, o CI e um script de build conseguem executar npm run typecheck sem depender da sua tela.

Se editor e terminal discordarem, confira a versão TypeScript selecionada pelo editor e o diretório do tsconfig. Também rode npx tsc --showConfig para ver a configuração final depois de heranças e valores padrão:

npx tsc --showConfig

O resultado é um JSON longo. Procure strict, rootDir, outDir e a lista files. Se seu arquivo não aparece ali, o problema é escopo de configuração, não o tipo escrito nele.

Missão: prove as quatro etapas

Crie src/frete.ts com uma função calcularFrete(peso: number): number. Para até cinco quilos, devolva 12; acima disso, devolva 20. Imprima os resultados para pesos 3 e 8.

function calcularFrete(peso: number): number {
  return peso <= 5 ? 12 : 20;
}

console.log(calcularFrete(3));
console.log(calcularFrete(8));

Seu critério de sucesso tem quatro marcas: npm run typecheck passa, npm run build cria dist/frete.js, o Node imprime 12 e 20, e a chamada calcularFrete('3') reproduz um erro antes de executar. Quando isso acontecer, avance para tipos básicos em TypeScript, onde a gente amplia o contrato além de um único número.