Instalar TypeScript com npm e verificar a versão

O TypeScript é um pacote npm chamado typescript. Instale no seu projeto e confira se funciona:

npm install --save-dev typescript
npx tsc --version

Version 7.0.2

O pacote fornece o comando tsc, o compilador do TypeScript. Você precisa de Node.js e npm (que vem junto com o Node.js) para instalá-lo; baixe o Node.js em nodejs.org ou pelo gerenciador de pacotes do seu sistema e confira com node --version.

Para experimentar o TypeScript, você não precisa instalar nada. Este bloco compila e roda no navegador:

function add(a: number, b: number): number {
    return a + b;
}

console.log(`2 + 3 = ${add(2, 3)}`);

Instalar o TypeScript em um projeto

A instalação recomendada é local, como dev dependency do projeto:

mkdir hello-ts
cd hello-ts
npm init -y
npm install --save-dev typescript

npm install --save-dev typescript (forma curta: npm i -D typescript) coloca o compilador em node_modules e o registra no package.json:

{
    "devDependencies": {
        "typescript": "^7.0.2"
    }
}

É uma dev dependency porque só é necessária para fazer o build do código, não para rodá-lo. Quem clonar o projeto e rodar npm install recebe a mesma versão do compilador.

Para rodar o compilador local, use o prefixo npx, que procura comandos em node_modules/.bin:

npx tsc --version

Dentro dos scripts do package.json você pode escrever tsc sem npx, porque o npm adiciona node_modules/.bin ao PATH dos scripts:

{
    "scripts": {
        "build": "tsc",
        "typecheck": "tsc --noEmit"
    }
}

Aí npm run build compila e npm run typecheck verifica os tipos sem gravar nenhum arquivo.

Verificar a versão do TypeScript

npm ls typescript

hello-ts@1.0.0 /home/ana/hello-ts
└── typescript@7.0.2

Se npx tsc --version e tsc --version mostram versões diferentes, o projeto tem o próprio compilador e o global é mais antigo ou mais novo. A versão do projeto é a que vale para o build dele.

Instalar o TypeScript globalmente

Uma instalação global dá a você um comando tsc em qualquer terminal, sem npx:

npm install -g typescript
tsc --version

No macOS e no Linux isso pode falhar com erros de permissão EACCES quando o Node.js foi instalado para o sistema todo. Instalar o Node.js com um gerenciador de versões como nvm ou fnm evita o problema, e sudo npm install -g não é recomendado.

Use o comando global para experimentos rápidos. Em um projeto de verdade, mantenha também uma instalação local: assim o package.json registra a versão, e uma atualização do compilador global não muda o build do projeto.

Instalar com pnpm, Yarn ou Bun

Todo gerenciador de pacotes JavaScript instala o mesmo pacote:

pnpm add -D typescript
yarn add -D typescript
bun add -d typescript

Rode o compilador com pnpm tsc, yarn tsc ou bunx tsc.

Criar um tsconfig.json com tsc --init

Um arquivo tsconfig.json marca uma pasta como projeto TypeScript e guarda as opções do compilador. Gere um:

npx tsc --init

Created a new tsconfig.json

You can learn more at https://aka.ms/tsconfig

O arquivo gerado (TypeScript 7) liga o strict e mais algumas verificações, usa "module": "nodenext" e "target": "esnext" e traz linhas comentadas para rootDir e outDir. Descomente essas duas para que o compilador leia de src e grave em dist:

{
    "compilerOptions": {
        "rootDir": "./src",
        "outDir": "./dist",
        "module": "nodenext",
        "target": "esnext",
        "types": [],
        "strict": true
    }
}

Essa é uma versão resumida; o arquivo real tem mais opções, cada uma com um comentário. A página sobre tsconfig explica o que elas fazem. Rodar npx tsc --init de novo na mesma pasta falha com error TS5054: A 'tsconfig.json' file is already defined, então ele nunca sobrescreve suas configurações.

Compilar o primeiro arquivo

Crie src/index.ts:

function greet(name: string): string {
    return `Hello, ${name}!`;
}

const names = ["Ada", "Grace", "Linus"];
for (const name of names) {
    console.log(greet(name));
}

Depois compile e rode:

npx tsc
node dist/index.js

Hello, Ada!
Hello, Grace!
Hello, Linus!

npx tsc sem argumentos lê o tsconfig.json, verifica os tipos de todos os arquivos incluídos e grava a saída em dist. Com as configurações geradas você recebe index.js mais index.d.ts (declarações de tipo) e arquivos .map (source maps) para cada um.

Duas coisas para saber sobre a saída:

• Por padrão, erros de tipo não impedem a saída. O tsc reporta os erros, termina com código diferente de zero e mesmo assim grava o JavaScript. Defina "noEmitOnError": true para não gravar nada enquanto houver erros.
• Com um tsconfig.json presente, não passe nomes de arquivos. npx tsc src/index.ts falha com error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Rode apenas npx tsc, ou adicione --ignoreConfig se quiser mesmo compilar um arquivo com as configurações padrão.

Modo watch

--watch (curto: -w) mantém o compilador rodando e recompila sempre que um arquivo muda:

npx tsc --watch

06:28:22 AM - Starting compilation in watch mode...

06:28:22 AM - Found 0 errors. Watching for file changes.

Deixe aberto em um terminal ao lado do editor. Pare com Ctrl+C.

Instalar uma versão específica do TypeScript

Adicione a versão depois do @:

npm install --save-dev typescript@7.0.2   # an exact version
npm install --save-dev typescript@6       # the newest 6.x
npm install --save-dev typescript@latest  # the newest stable release
npm install --save-dev typescript@next    # nightly builds of the next version

O TypeScript 6 é a última versão cujo compilador é escrito em JavaScript. Algumas ferramentas que chamam a API JavaScript do compilador ainda precisam dele, e a página do TypeScript 7 trata disso e de como atualizar.

Configurar o editor

O VS Code tem suporte a TypeScript embutido: abra um arquivo .ts e você tem erros sublinhados, autocompletar, tipos ao passar o mouse e renomeação sem instalar nada. Para ter a velocidade do TypeScript 7 no editor, o time do TypeScript publica uma extensão própria que troca o VS Code para o language server nativo do TypeScript 7. O WebStorm e as outras IDEs da JetBrains suportam TypeScript de fábrica, e Neovim, Vim, Emacs, Zed e Sublime Text usam um language server de TypeScript pelo suporte a LSP.

Erros comuns na instalação

This is not the tsc command you are looking for. Você rodou npx tsc em uma pasta sem TypeScript instalado, e o npx baixou um pacote antigo que por acaso se chama tsc. Instale o pacote certo com npm install --save-dev typescript.

tsc: command not found, ou 'tsc' is not recognized as an internal or external command no Windows. O TypeScript não está instalado globalmente, ou a pasta global do npm não está no seu PATH. Use npx tsc em um projeto com instalação local, ou instale globalmente e abra um terminal novo.

error TS2591: Cannot find name 'process' (ou require; __dirname dá TS2304). As APIs do próprio Node.js têm os tipos em um pacote separado. Instale com npm install --save-dev @types/node e adicione "types": ["node"] em compilerOptions: o TypeScript 7 não carrega mais automaticamente todos os pacotes @types instalados.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Seus arquivos estão em src e você definiu outDir, mas não rootDir. Adicione "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. O npm init -y grava "type": "commonjs" no package.json, então a configuração do tsc --init ("module": "nodenext" com verbatimModuleSyntax) trata todo arquivo .ts como CommonJS, onde import e export não são permitidos. Troque para "type": "module" e escreva imports relativos com a extensão .js: import { add } from "./math.js".