Exécuter un fichier TypeScript : tsc, Node.js, tsx, ts-node

Un fichier TypeScript ne peut pas s'exécuter tel quel, car les navigateurs et les moteurs JavaScript ne comprennent pas les annotations de type. Il faut d'abord retirer les types. Ce travail revient soit au compilateur TypeScript (tsc), qui vérifie aussi les types, soit à un outil plus rapide qui se contente de les supprimer. Le moyen le plus rapide d'exécuter le code de cette page est le bouton 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}`);
}

Sortie :

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

Tous les blocs exécutables de cette documentation fonctionnent de la même manière : le code est vérifié par TypeScript 7 avec strict activé, et il ne s'exécute que s'il n'y a aucune erreur de type. Pour des essais plus longs, le playground TypeScript est le même éditeur sur une page dédiée. La suite de cette page traite de l'exécution de fichiers .ts sur votre propre machine.

Les options en un coup d'œil

C'est la première colonne qui surprend : la plupart des options rapides exécutent du code qui contient des erreurs de type. Un projet typique exécute le code avec l'une d'elles et lance tsc --noEmit à part, dans l'éditeur et en CI, pour détecter les erreurs.

Compiler avec tsc, puis exécuter avec Node

C'est l'approche qui fonctionne partout et qui vérifie tout. Avec TypeScript installé dans le projet et un tsconfig.json qui règle "rootDir": "./src" et "outDir": "./dist" :

npx tsc
node dist/index.js

tsc vérifie les types de tous les fichiers, puis écrit les fichiers .js dans dist. Pour un fichier isolé hors projet, passez le nom du fichier. Le compilateur utilise alors les options par défaut et écrit index.js à côté de index.ts :

npx tsc index.ts
node index.js

(Si le dossier contient un tsconfig.json, tsc refuse les noms de fichiers avec error TS5112 ; lancez simplement npx tsc, ou ajoutez --ignoreConfig.)

Par défaut, tsc écrit quand même le JavaScript en cas d'erreurs de type, donc node peut exécuter un programme qui a échoué à la vérification. Ajoutez "noEmitOnError": true à la configuration pour l'empêcher, ou enchaînez les commandes dans un script pour que la seconde étape ne s'exécute que si la première réussit :

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

Pendant le développement, npx tsc --watch recompile à chaque enregistrement.

Exécuter TypeScript directement avec Node.js

Les versions actuelles de Node.js exécutent elles-mêmes les fichiers .ts :

node index.ts

Node retire les annotations de type, en les remplaçant par des espaces pour que les numéros de ligne des stack traces restent justes, et exécute ce qui reste. Cette fonction est active par défaut depuis Node.js 23.6.0 et 22.18.0, n'affiche plus d'avertissement depuis 24.3.0 et 22.18.0, et a été déclarée stable dans Node.js 24.12.0 et 25.2.0. Les versions antérieures qui la proposent (22.6 à 22.17, et 23.0 à 23.5) demandent l'option : node --experimental-strip-types index.ts.

Quatre règles l'accompagnent :

• Aucune vérification des types. Un fichier contenant const age: number = "forty" s'exécute et affiche forty.
• Uniquement une syntaxe effaçable. Tout ce qui doit devenir du code JavaScript, au lieu de disparaître, est refusé : enum, les blocs namespace contenant du code exécutable, les propriétés de paramètres du constructeur comme constructor(private name: string), et les alias import x = require(). Node s'arrête avec SyntaxError [ERR_UNSUPPORTED_TYPESCRIPT_SYNTAX]: TypeScript enum is not supported in strip-only mode.
• tsconfig.json est ignoré. Des options comme paths ou target n'ont aucun effet.
• Les imports demandent de vrais noms de fichiers. Écrivez import { add } from "./math.ts", avec l'extension, et marquez les imports de types avec type : import { add, type Pair } from "./math.ts". Sans type, Node cherche un export d'exécution nommé Pair et échoue avec SyntaxError: The requested module './math.ts' does not provide an export named 'Pair'.

Deux options du compilateur font appliquer les mêmes règles par tsc, pour que l'éditeur vous prévienne avant Node : "erasableSyntaxOnly": true signale error TS1294: This syntax is not allowed when 'erasableSyntaxOnly' is enabled. sur un enum, et "verbatimModuleSyntax": true impose le mot-clé type sur les imports de types uniquement. Pour continuer à écrire les extensions .ts dans les imports tout en compilant avec tsc, ajoutez "rewriteRelativeImportExtensions": true, qui transforme ./math.ts en ./math.js dans la sortie.

Node.js 24 propose aussi --experimental-transform-types, qui génère du code pour les enums et les propriétés de paramètres au lieu de les refuser. Il affiche un ExperimentalWarning, et Node.js 26 a supprimé cette option : ne construisez rien dessus.

Ce bloc utilise deux fonctionnalités que node index.ts refuse. Il s'exécute ici parce que l'éditeur le compile avec le compilateur TypeScript, qui génère du JavaScript pour les deux :

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 version effaçable du même code utilise un objet const et un champ ordinaire, que Node peut exécuter tel quel :

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 exécute un fichier TypeScript en une seule étape, sans configuration ni restriction de syntaxe :

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

Il transforme le code avec esbuild : les enums, les namespaces et les propriétés de paramètres fonctionnent, et les imports sans extension se résolvent comme dans un bundler. Comme le type stripping de Node, il ne vérifie pas les types. C'est le choix courant pour les scripts, les serveurs de développement et les tests sur des versions de Node.js antérieures au type stripping, ou quand le code utilise une syntaxe que Node refuse.

ts-node

ts-node a été pendant des années la méthode standard pour exécuter TypeScript sous Node.js, et c'est encore ce qu'utilisent beaucoup de tutoriels et de projets plus anciens (npx ts-node index.ts, node -r ts-node/register). Il vérifie les types par défaut, via l'API JavaScript du compilateur TypeScript.

Cette API est justement ce que TypeScript 7 ne fournit pas : son compilateur est un programme natif, et le paquet typescript 7 n'expose aucune API de compilateur à JavaScript. Avec TypeScript 7 installé, ts-node plante avant d'exécuter quoi que ce soit :

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

La dernière version de ts-node, la 10.9.2, date de décembre 2023. Pour du nouveau code, utilisez tsx ou node index.ts. Une configuration existante qui dépend de ts-node continue de fonctionner si le projet reste sur TypeScript 6 (npm install --save-dev typescript@6) et possède un tsconfig.json, même un simple {}. Sans ce fichier, ts-node se rabat sur des valeurs par défaut intégrées qui incluent la résolution de modules node10, dépréciée par TypeScript 6, et npx ts-node index.ts se termine sans exécuter le fichier ni afficher d'erreur.

Deno et Bun

Ces deux runtimes traitent TypeScript comme un type de fichier à part entière :

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

bun index.ts         # runs without checking

Aucun des deux n'a besoin que typescript soit installé ni d'un tsconfig.json, et tous deux acceptent enum et les autres fonctionnalités non effaçables. Deno embarque sa propre copie du compilateur TypeScript pour deno check. Bun se contente de retirer les types : dans un projet Bun, vous installez donc quand même typescript et lancez tsc --noEmit pour trouver les erreurs de type.

Les erreurs de type n'arrêtent le programme qu'avec tsc

Seules les méthodes qui lancent tsc d'abord refusent d'exécuter un programme contenant des erreurs de type. L'éditeur de cette page en fait partie, ce bloc s'arrête donc au compilateur :

// 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'.

Enregistré dans un fichier et lancé avec node index.ts, npx tsx index.ts ou bun index.ts, le même code s'exécute et affiche 12, car 3 * "4" convertit la chaîne. C'est pourquoi il faut garder tsc --noEmit dans la boucle, même quand un outil plus rapide exécute le code :

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

Laquelle choisir ?

• Pour apprendre ou faire un test rapide : le bouton Run de ces pages, ou le playground.
• Un script ou un petit outil sur un Node.js récent : node index.ts, avec erasableSyntaxOnly dans la configuration pour que l'éditeur signale tout ce que Node refuserait.
• N'importe quel projet Node.js, n'importe quelle syntaxe : tsx pour exécuter, tsc --noEmit pour vérifier.
• Une bibliothèque ou tout ce que vous publiez : tsc, car il écrit aussi les fichiers .d.ts dont vos utilisateurs ont besoin.
• Du code frontend : votre bundler ou votre framework (Vite, Next.js, Angular CLI) exécute le TypeScript pour vous ; ajoutez tsc --noEmit pour la vérification.