Instalar TypeScript no Projeto do Zero

O Que É o Setup de TypeScript

Configurar TypeScript num projeto significa três coisas: instalar o compilador, criar o arquivo de configuração (tsconfig.json) e definir como o código TypeScript vai ser transformado em JavaScript. Parece muito, mas na prática são 5 minutos de setup.

TypeScript não roda direto no navegador nem no Node.js. Ele precisa ser compilado pra JavaScript primeiro. O compilador tsc lê seus arquivos .ts, verifica os tipos e gera arquivos .js equivalentes. Esse processo acontece no build. Em produção, só JavaScript roda.

Durante o desenvolvimento, você pode usar ts-node pra rodar TypeScript direto sem compilar manualmente. Ou usar tsx, que é mais rápido porque usa esbuild por baixo. No frontend com frameworks como Next.js ou Vite, o setup já vem quase pronto e você só precisa ajustar o tsconfig.

Mas entender o que acontece por baixo é o que separa quem "usa TypeScript" de quem domina TypeScript. Quando algo quebra no build, quem entende o tsc resolve em minutos. Quem não entende fica horas no Stack Overflow. Vamos configurar tudo do zero, sem framework, sem mágica.

O tsconfig.json é o cérebro do TypeScript no seu projeto. Cada opção controla um aspecto: qual versão de JavaScript gerar, quão rigorosa é a checagem de tipos, onde ficam os arquivos fonte e onde ficam os compilados. Vamos ver cada opção importante e por que ela existe.

Como Instalar TypeScript Passo a Passo

Do zero absoluto. Abra o terminal e siga cada passo. Em 10 minutos você tem TypeScript rodando.

Exemplos Práticos de Configuração

Vamos ver cada parte da configuração com código real e explicações de por que cada opção existe.

Comandos de Instalação

# Criar projeto do zero
mkdir meu-projeto
cd meu-projeto
npm init -y

# Instalar TypeScript e ferramentas
npm install typescript --save-dev
npm install ts-node --save-dev
npm install @types/node --save-dev

# Gerar tsconfig.json
npx tsc --init

# Criar estrutura de pastas
mkdir src
mkdir dist

O @types/node é o pacote de tipos pra APIs nativas do Node.js. Sem ele, console.log, process.env, Buffer e tudo mais do Node fica sem tipagem. Sempre instale quando o projeto roda em Node. Pra projetos de browser, instale @types/web ou os tipos específicos das libs que usa.

tsconfig.json Recomendado

{
  "compilerOptions": {
    // Qual versão de JS gerar
    "target": "ES2020",

    // Sistema de módulos
    "module": "commonjs",

    // Onde ficam os arquivos .ts
    "rootDir": "./src",

    // Onde ficam os arquivos .js compilados
    "outDir": "./dist",

    // Modo estrito - SEMPRE ative
    "strict": true,

    // Resolve imports de módulos corretamente
    "esModuleInterop": true,

    // Garante consistência em nomes de arquivos
    "forceConsistentCasingInFileNames": true,

    // Pula checagem de tipos em node_modules
    "skipLibCheck": true,

    // Resolve JSON imports
    "resolveJsonModule": true,

    // Gera source maps pra debug
    "sourceMap": true,

    // Gera arquivos .d.ts de declaração
    "declaration": true
  },
  "include": ["src/**/*"],
  "exclude": ["node_modules", "dist"]
}

Cada opção tem um motivo. target define qual versão de JavaScript o compilador gera. ES2020 é seguro pra Node.js 14+ e navegadores modernos. Pra projetos que precisam de compatibilidade com navegadores antigos, use ES2017 ou ES2015. strict ativa todas as checagens rigorosas de tipo. É o que faz TypeScript valer a pena.

A opção module define o sistema de módulos. commonjs é o padrão do Node.js (require/module.exports). Se seu projeto usa ESModules (import/export nativo), troque pra nodenext ou esnext. Projetos modernos cada vez mais migram pra ESModules, mas commonjs ainda é o mais estável em 2025.

Entendendo o strict Mode

// strict: true ativa TODAS essas opções de uma vez:
// "noImplicitAny": true        - proíbe any implícito
// "strictNullChecks": true     - null/undefined são tipos separados
// "strictFunctionTypes": true  - checagem estrita de tipos de função
// "strictBindCallApply": true  - checa bind, call e apply
// "strictPropertyInitialization": true - classes devem inicializar props
// "noImplicitThis": true       - proíbe this implícito
// "alwaysStrict": true         - gera "use strict" no JS

// Sem strict, isso é aceito silenciosamente:
function somar(a, b) {  // a e b são 'any' implícito
  return a + b;
}
somar("texto", 42);  // sem erro, resultado: "texto42" (bug!)

// Com strict, TypeScript pede tipos:
function somarCorreto(a: number, b: number): number {
  return a + b;
}
// somarCorreto("texto", 42);  // Error: Argument of type 'string'...

strict: true é inegociável. Sem ele, TypeScript aceita tanta coisa perigosa que não vale a pena usar. É como instalar um antivírus e deixar desligado. Eu sei que ativar strict num projeto existente gera centenas de erros. Mas cada erro que aparece é um bug que tava escondido no seu código. Corrija um por um, vale o esforço.

Primeiro Arquivo TypeScript

// src/index.ts

interface Usuario {
  nome: string;
  email: string;
  idade: number;
}

function saudar(usuario: Usuario): string {
  return `Olá, ${usuario.nome}! Você tem ${usuario.idade} anos.`;
}

const maria: Usuario = {
  nome: "Maria",
  email: "maria@email.com",
  idade: 28,
};

console.log(saudar(maria));
// Output: Olá, Maria! Você tem 28 anos.

Scripts no package.json

// package.json - seção scripts
{
  "scripts": {
    "build": "tsc",
    "start": "node dist/index.js",
    "dev": "ts-node src/index.ts",
    "watch": "tsc --watch"
  }
}

// Uso:
// npm run build    → compila TypeScript pra JavaScript
// npm start        → roda o JavaScript compilado
// npm run dev      → roda TypeScript direto (desenvolvimento)
// npm run watch    → recompila automaticamente quando salva

O script watch é ouro durante o desenvolvimento. Ele fica observando mudanças nos arquivos .ts e recompila automaticamente. Você salva o arquivo e em menos de 1 segundo o .js atualizado aparece na pasta dist/. Se preferir algo mais moderno, tsx watch faz o mesmo com velocidade superior.

Estrutura Final do Projeto

meu-projeto/
├── node_modules/
├── src/
│   ├── index.ts          # Ponto de entrada
│   ├── types/
│   │   └── index.ts      # Tipos compartilhados
│   └── utils/
│       └── helpers.ts    # Funções utilitárias
├── dist/                  # Gerado pelo tsc (não committar)
│   ├── index.js
│   ├── index.js.map
│   └── index.d.ts
├── package.json
├── tsconfig.json
├── .gitignore             # Inclua dist/ e node_modules/
└── README.md

Essa estrutura é o padrão da indústria. Código fonte em src/, código compilado em dist/, tipos compartilhados numa pasta types/. A pasta dist/ é gerada pelo compilador. Não commite ela no git. Quem clonar o projeto roda npm run build pra gerar.

.gitignore para Projetos TypeScript

# .gitignore
node_modules/
dist/
*.js.map
.env
.DS_Store

O source map (.js.map) conecta o JavaScript compilado ao TypeScript original. Sem ele, quando um erro acontece em produção, o stack trace aponta pra linha do .js que não tem nada a ver com seu .ts. Com source map, o debug aponta pro arquivo TypeScript original. Em desenvolvimento é obrigatório. Em produção, depende do cenário de segurança.

Alternativa Rápida: tsx

# tsx é mais rápido que ts-node
npm install tsx --save-dev

# Rodar direto
npx tsx src/index.ts

# Com watch mode
npx tsx watch src/index.ts

# No package.json
{
  "scripts": {
    "dev": "tsx watch src/index.ts"
  }
}

tsx usa esbuild por baixo, então é absurdamente mais rápido que ts-node pra desenvolvimento. A diferença é perceptível em projetos grandes: ts-node demora 3-4 segundos, tsx inicia em menos de 1. Pra produção, continue usando tsc pra compilar e node pra rodar o JavaScript. tsx é ferramenta de desenvolvimento.

Erros Comuns na Instalação