Installare TypeScript con npm e controllare la versione

TypeScript è un pacchetto npm chiamato typescript. Installalo nel tuo progetto e controlla che funzioni:

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

Version 7.0.2

Il pacchetto fornisce il comando tsc, il compilatore TypeScript. Per installarlo ti servono Node.js e npm (che arriva insieme a Node.js); scarica Node.js da nodejs.org o dal gestore di pacchetti del tuo sistema, e controllalo con node --version.

Per provare TypeScript non devi installare nulla. Questo blocco viene compilato ed eseguito nel browser:

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

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

Installare TypeScript in un progetto

L'installazione consigliata è locale, come dev dependency del progetto:

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

npm install --save-dev typescript (forma breve npm i -D typescript) mette il compilatore in node_modules e lo registra in package.json:

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

È una dev dependency perché serve solo per compilare il codice, non per eseguirlo. Chiunque cloni il progetto ed esegua npm install ottiene la stessa versione del compilatore.

Per eseguire il compilatore locale, anteponi npx, che trova i comandi in node_modules/.bin:

npx tsc --version

Negli script di package.json puoi scrivere tsc senza npx, perché npm aggiunge node_modules/.bin al PATH degli script:

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

A questo punto npm run build compila e npm run typecheck controlla i tipi senza scrivere alcun file.

Controllare la versione di TypeScript

npm ls typescript

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

Se npx tsc --version e tsc --version stampano versioni diverse, il progetto ha il suo compilatore e quello globale è più vecchio o più nuovo. Per la build del progetto conta la versione del progetto.

Installare TypeScript globalmente

Un'installazione globale ti dà un comando tsc in ogni terminale, senza npx:

npm install -g typescript
tsc --version

Su macOS e Linux può fallire con errori di permesso EACCES quando Node.js è installato a livello di sistema. Installare Node.js con un version manager come nvm o fnm evita il problema, mentre sudo npm install -g è sconsigliato.

Usa il comando globale per esperimenti veloci. Per un progetto vero, tieni anche un'installazione locale: package.json registra allora la versione, e un aggiornamento del compilatore globale non può cambiare il modo in cui il progetto viene compilato.

Installare con pnpm, Yarn o Bun

Ogni gestore di pacchetti JavaScript installa lo stesso pacchetto:

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

Esegui il compilatore con pnpm tsc, yarn tsc o bunx tsc.

Creare un tsconfig.json con tsc --init

Un file tsconfig.json indica che una cartella è un progetto TypeScript e contiene le opzioni del compilatore. Generane uno:

npx tsc --init

Created a new tsconfig.json

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

Il file generato (TypeScript 7) attiva strict e qualche altro controllo, usa "module": "nodenext" e "target": "esnext", e ha righe commentate per rootDir e outDir. Togli il commento a queste due così il compilatore legge da src e scrive in dist:

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

Questa è una versione abbreviata; il file vero ha più opzioni, ognuna con un commento. La pagina su tsconfig spiega cosa fanno. Eseguire di nuovo npx tsc --init nella stessa cartella fallisce con error TS5054: A 'tsconfig.json' file is already defined, quindi non sovrascrive mai le tue impostazioni.

Compilare il tuo primo file

Crea 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));
}

Poi compila ed esegui:

npx tsc
node dist/index.js

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

npx tsc senza argomenti legge tsconfig.json, controlla i tipi di ogni file incluso e scrive l'output in dist. Con le impostazioni generate ottieni index.js più index.d.ts (dichiarazioni di tipo) e file .map (source map) per ciascuno.

Due cose da sapere sull'output:

• Gli errori di tipo di default non bloccano l'output. tsc segnala gli errori, esce con un codice diverso da zero e scrive comunque il JavaScript. Imposta "noEmitOnError": true per non scrivere nulla finché ci sono errori.
• Se c'è un tsconfig.json, non passare nomi di file. npx tsc src/index.ts fallisce con error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Esegui semplicemente npx tsc, oppure aggiungi --ignoreConfig se vuoi davvero compilare un solo file con le impostazioni di default.

Modalità watch

--watch (breve -w) tiene il compilatore attivo e ricompila ogni volta che un file cambia:

npx tsc --watch

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

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

Lascialo aperto in un terminale accanto all'editor. Fermalo con Ctrl+C.

Installare una versione specifica di TypeScript

Aggiungi la versione dopo @:

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

TypeScript 6 è l'ultima versione con il compilatore scritto in JavaScript. Alcuni strumenti che chiamano l'API JavaScript del compilatore ne hanno ancora bisogno, come spiega la pagina su TypeScript 7 insieme a come aggiornare.

Configurare l'editor

VS Code ha il supporto a TypeScript integrato: apri un file .ts e hai sottolineature degli errori, autocompletamento, tipi al passaggio del mouse e rinomina senza installare nulla. Per avere la velocità di TypeScript 7 nell'editor, il team di TypeScript pubblica un'estensione apposita che fa passare VS Code al language server nativo di TypeScript 7. WebStorm e gli altri IDE JetBrains supportano TypeScript senza configurazioni, e Neovim, Vim, Emacs, Zed e Sublime Text usano un language server TypeScript tramite il loro supporto LSP.

Errori comuni di installazione

This is not the tsc command you are looking for. Hai eseguito npx tsc in una cartella senza TypeScript installato, e npx ha scaricato un pacchetto deprecato che per caso si chiama tsc. Installa quello vero con npm install --save-dev typescript.

tsc: command not found, oppure 'tsc' is not recognized as an internal or external command su Windows. TypeScript non è installato globalmente, oppure la cartella globale di npm non è nel tuo PATH. Usa npx tsc in un progetto con un'installazione locale, oppure installa globalmente e apri un nuovo terminale.

error TS2591: Cannot find name 'process' (o require; __dirname dà TS2304). Le API di Node.js hanno i loro tipi in un pacchetto separato. Installalo con npm install --save-dev @types/node, poi aggiungi "types": ["node"] a compilerOptions: TypeScript 7 non carica più in automatico tutti i pacchetti @types installati.

error TS5011: The common source directory of 'tsconfig.json' is './src'. I tuoi file sono in src e hai impostato outDir ma non rootDir. Aggiungi "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y scrive "type": "commonjs" in package.json, quindi la configurazione di tsc --init ("module": "nodenext" con verbatimModuleSyntax) tratta ogni file .ts come CommonJS, dove import ed export non sono ammessi. Cambialo in "type": "module" e scrivi gli import relativi con l'estensione .js: import { add } from "./math.js".