Come eseguire un file TypeScript: tsc, Node.js, tsx, ts-node

Un file TypeScript non si può eseguire così com'è, perché i browser e i motori JavaScript non capiscono le annotazioni di tipo. Prima qualcosa deve togliere i tipi. Quel qualcosa è il compilatore TypeScript (tsc), che controlla anche i tipi, oppure uno strumento più veloce che si limita a rimuoverli. Il modo più rapido per eseguire il codice di questa pagina è il pulsante Run:

type Task = { title: string; done: boolean };

const tasks: Task[] = [
    { title: "Install TypeScript", done: true },
    { title: "Run a .ts file", done: false },
];

for (const task of tasks) {
    console.log(`${task.done ? "[x]" : "[ ]"} ${task.title}`);
}

Output:

[x] Install TypeScript
[ ] Run a .ts file

Ogni blocco eseguibile di questa documentazione funziona allo stesso modo: il codice viene controllato da TypeScript 7 con strict attivo, e viene eseguito solo se non ci sono errori di tipo. Per esperimenti più lunghi, il playground TypeScript è lo stesso editor su una pagina tutta sua. Il resto di questa pagina riguarda l'esecuzione di file .ts sul tuo computer.

Le opzioni in sintesi

La colonna che sorprende è la prima: la maggior parte delle opzioni veloci esegue codice che contiene errori di tipo. Un progetto tipico esegue il codice con una di queste e lancia tsc --noEmit a parte, nell'editor e nella CI, per intercettare gli errori.

Compilare con tsc, poi eseguire con Node

È l'approccio che funziona ovunque e controlla tutto. Con TypeScript installato nel progetto e un tsconfig.json che imposta "rootDir": "./src" e "outDir": "./dist":

npx tsc
node dist/index.js

tsc controlla i tipi di tutti i file, poi scrive i file .js in dist. Per un singolo file senza progetto, passa il nome del file. In quel caso usa le opzioni predefinite e scrive index.js accanto a index.ts:

npx tsc index.ts
node index.js

(Se la cartella ha un tsconfig.json, tsc rifiuta i nomi di file con error TS5112; lancia semplicemente npx tsc, oppure aggiungi --ignoreConfig.)

Per impostazione predefinita tsc scrive comunque il JavaScript quando ci sono errori di tipo, quindi node può eseguire un programma che non ha superato il controllo. Aggiungi "noEmitOnError": true alla configurazione per impedirlo, oppure concatena i comandi in uno script così che il secondo passaggio parta solo se il primo riesce:

{
    "scripts": {
        "build": "tsc",
        "start": "tsc && node dist/index.js"
    }
}

Durante lo sviluppo, npx tsc --watch ricompila a ogni salvataggio.

Eseguire TypeScript direttamente con Node.js

Le versioni attuali di Node.js eseguono da sole i file .ts:

node index.ts

Node rimuove le annotazioni di tipo, sostituendole con spazi così che i numeri di riga negli stack trace corrispondano ancora, ed esegue ciò che resta. È attivo per impostazione predefinita da Node.js 23.6.0 e 22.18.0, non stampa avvisi da 24.3.0 e 22.18.0, ed è stato dichiarato stabile in Node.js 24.12.0 e 25.2.0. Le versioni precedenti che hanno la funzionalità (da 22.6 a 22.17, e da 23.0 a 23.5) richiedono il flag: node --experimental-strip-types index.ts.

Porta con sé quattro regole:

• Nessun controllo dei tipi. Un file con const age: number = "forty" viene eseguito e stampa forty.
• Solo sintassi cancellabile. Tutto ciò che deve diventare codice JavaScript, invece di sparire, viene rifiutato: enum, blocchi namespace con codice eseguibile, parameter properties del costruttore come constructor(private name: string) e alias import x = require(). Node si ferma con SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json viene ignorato. Opzioni come paths o target non hanno effetto.
• Gli import richiedono nomi di file reali. Scrivi import { add } from "./math.ts", con l'estensione, e segna gli import di soli tipi con type: import { add, type Pair } from "./math.ts". Senza type, Node cerca un export di runtime chiamato Pair e fallisce con SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Due opzioni del compilatore fanno applicare a tsc le stesse regole, così l'editor ti avvisa prima di Node: "erasableSyntaxOnly": true segnala error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. su un enum, e "verbatimModuleSyntax": true richiede la parola chiave type negli import di soli tipi. Per continuare a scrivere le estensioni .ts negli import e compilare comunque con tsc, aggiungi "rewriteRelativeImportExtensions": true, che trasforma ./math.ts in ./math.js nell'output.

Node.js 24 ha anche --experimental-transform-types, che genera codice per enum e parameter properties invece di rifiutarli. Stampa un ExperimentalWarning, e Node.js 26 ha rimosso il flag, quindi non costruirci sopra.

Questo blocco usa due funzionalità che node index.ts rifiuta. Qui funziona perché l'editor lo compila con il compilatore TypeScript, che genera JavaScript per entrambe:

enum Level {
    Low = 1,
    High = 3,
}

class Counter {
    constructor(private count: number) {} // a parameter property

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

La versione cancellabile dello stesso codice usa un oggetto const e un campo normale, che Node può eseguire così com'è:

const Level = { Low: 1, High: 3 } as const;
type Level = (typeof Level)[keyof typeof Level]; // 1 | 3

class Counter {
    private count: number;

    constructor(count: number) {
        this.count = count;
    }

    add(level: Level): number {
        this.count += level;
        return this.count;
    }
}

const c = new Counter(0);
console.log(c.add(Level.Low), c.add(Level.High)); // 1 4

tsx

tsx esegue un file TypeScript in un solo passaggio, senza configurazione e senza restrizioni sulla sintassi:

npm install --save-dev tsx
npx tsx index.ts
npx tsx watch index.ts   # rerun on every change

Trasforma il codice con esbuild, quindi enum, namespace e parameter properties funzionano, e gli import senza estensione si risolvono come in un bundler. Come il type stripping di Node, non controlla i tipi. È la scelta comune per script, server di sviluppo e test sulle versioni di Node.js precedenti al type stripping, o quando il codice usa sintassi che Node rifiuta.

ts-node

Per anni ts-node è stato il modo standard di eseguire TypeScript su Node.js, ed è ancora ciò che usano molti tutorial e progetti meno recenti (npx ts-node index.ts, node -r ts-node/register). Controlla i tipi per impostazione predefinita, usando l'API JavaScript del compilatore TypeScript.

Quell'API è proprio ciò che TypeScript 7 non include: il suo compilatore è un programma nativo, e il pacchetto typescript 7 non espone alcuna API del compilatore a JavaScript. Con TypeScript 7 installato, ts-node va in crash prima di eseguire qualsiasi cosa:

TypeError: Cannot read properties of undefined (reading 'fileExists')
    at readConfig (/project/node_modules/ts-node/dist/configuration.js:91:33)

L'ultima versione di ts-node, la 10.9.2, risale a dicembre 2023. Per il codice nuovo usa tsx o node index.ts. Una configurazione esistente che dipende da ts-node continua a funzionare se il progetto resta su TypeScript 6 (npm install --save-dev typescript@6) e ha un tsconfig.json, anche vuoto come {}. Senza, ts-node ripiega su impostazioni predefinite interne che includono la module resolution node10 deprecata da TypeScript 6, e npx ts-node index.ts termina senza eseguire il file né stampare un errore.

Deno e Bun

Entrambi i runtime trattano TypeScript come un tipo di file di prima classe:

deno run index.ts    # runs without checking
deno check index.ts  # type-checks, reports errors, runs nothing

bun index.ts         # runs without checking

Nessuno dei due richiede typescript installato o un tsconfig.json, ed entrambi supportano enum e le altre funzionalità non cancellabili. Deno include una propria copia del compilatore TypeScript per deno check. Bun si limita a togliere i tipi, quindi in un progetto Bun installi comunque typescript e lanci tsc --noEmit per trovare gli errori di tipo.

Gli errori di tipo fermano il programma solo con tsc

Solo i percorsi che eseguono prima tsc si rifiutano di eseguire un programma con errori di tipo. L'editor di questa pagina è uno di questi, quindi questo blocco si ferma al compilatore:

// This does not compile: the editor type-checks before it runs anything.
function area(width: number, height: number): number {
    return width * height;
}

console.log(area(3, "4"));

index.ts(6,21): error TS2345: Argument of type 'string' is not assignable to parameter of type 'number'.

Salvato come file ed eseguito con node index.ts, npx tsx index.ts o bun index.ts, lo stesso codice viene eseguito e stampa 12, perché 3 * "4" converte la stringa. È il motivo per tenere tsc --noEmit nel ciclo anche quando è uno strumento più veloce a eseguire il codice:

{
    "scripts": {
        "dev": "tsx watch src/index.ts",
        "typecheck": "tsc --noEmit"
    }
}

Quale usare?

• Per imparare, o per una prova veloce: il pulsante Run di queste pagine, oppure il playground.
• Uno script o un piccolo strumento su una versione attuale di Node.js: node index.ts, con erasableSyntaxOnly nella configurazione così che l'editor segnali tutto ciò che Node rifiuterebbe.
• Qualsiasi progetto Node.js, qualsiasi sintassi: tsx per eseguire, tsc --noEmit per controllare.
• Una libreria o qualsiasi cosa tu pubblichi: tsc, perché scrive anche i file .d.ts di cui hanno bisogno i tuoi utenti.
• Codice front end: il tuo bundler o framework (Vite, Next.js, Angular CLI) esegue TypeScript al posto tuo; aggiungi tsc --noEmit per il controllo.