Installer TypeScript avec npm et vérifier sa version

TypeScript est un paquet npm nommé typescript. Installez-le dans votre projet et vérifiez qu'il fonctionne :

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

Version 7.0.2

Le paquet fournit la commande tsc, le compilateur TypeScript. Il vous faut Node.js et npm (livré avec Node.js) pour l'installer ; récupérez Node.js sur nodejs.org ou via le gestionnaire de paquets de votre système, et vérifiez-le avec node --version.

Vous n'avez rien besoin d'installer pour essayer TypeScript. Ce bloc se compile et s'exécute dans votre navigateur :

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

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

Installer TypeScript dans un projet

L'installation recommandée est locale, comme dépendance de développement du projet :

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

npm install --save-dev typescript (forme courte npm i -D typescript) place le compilateur dans node_modules et l'enregistre dans package.json :

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

C'est une dépendance de développement parce qu'elle ne sert qu'à construire le code, pas à l'exécuter. Toute personne qui clone le projet et lance npm install obtient la même version du compilateur.

Pour lancer le compilateur local, préfixez-le avec npx, qui trouve les commandes dans node_modules/.bin :

npx tsc --version

Dans les scripts de package.json, vous pouvez écrire tsc sans npx, car npm ajoute node_modules/.bin au PATH des scripts :

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

Ensuite, npm run build compile et npm run typecheck vérifie les types sans écrire aucun fichier.

Vérifier la version de TypeScript

npm ls typescript

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

Si npx tsc --version et tsc --version affichent des versions différentes, le projet a son propre compilateur et la version globale est plus ancienne ou plus récente. C'est la version du projet qui compte pour son build.

Installer TypeScript globalement

Une installation globale vous donne une commande tsc dans n'importe quel terminal, sans npx :

npm install -g typescript
tsc --version

Sur macOS et Linux, cela peut échouer avec des erreurs de permission EACCES quand Node.js a été installé pour tout le système. Installer Node.js via un gestionnaire de versions comme nvm ou fnm évite ce problème, et sudo npm install -g est déconseillé.

Utilisez la commande globale pour les essais rapides. Pour un vrai projet, gardez aussi une installation locale : package.json enregistre alors la version, et une mise à jour du compilateur global ne peut pas changer la façon dont le projet se construit.

Installer avec pnpm, Yarn ou Bun

Tous les gestionnaires de paquets JavaScript installent le même paquet :

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

Lancez le compilateur avec pnpm tsc, yarn tsc ou bunx tsc.

Créer un tsconfig.json avec tsc --init

Un fichier tsconfig.json marque un dossier comme projet TypeScript et contient les options du compilateur. Générez-en un :

npx tsc --init

Created a new tsconfig.json

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

Le fichier généré (TypeScript 7) active strict et quelques vérifications supplémentaires, utilise "module": "nodenext" et "target": "esnext", et contient des lignes commentées pour rootDir et outDir. Décommentez ces deux lignes pour que le compilateur lise depuis src et écrive dans dist :

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

Ceci est une vue abrégée ; le vrai fichier contient plus d'options, chacune avec un commentaire. La page tsconfig explique à quoi elles servent. Relancer npx tsc --init dans le même dossier échoue avec error TS5054: A 'tsconfig.json' file is already defined, la commande n'écrase donc jamais vos réglages.

Compiler votre premier fichier

Créez 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));
}

Puis compilez et exécutez :

npx tsc
node dist/index.js

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

npx tsc sans argument lit tsconfig.json, vérifie les types de chaque fichier inclus et écrit le résultat dans dist. Avec les réglages générés, vous obtenez pour chaque fichier un index.js, plus un index.d.ts (déclarations de types) et des fichiers .map (source maps).

Deux choses à savoir sur la sortie :

• Par défaut, les erreurs de type n'empêchent pas la sortie. tsc signale les erreurs, se termine avec un code non nul et écrit quand même le JavaScript. Réglez "noEmitOnError": true pour ne rien écrire tant qu'il reste des erreurs.
• Avec un tsconfig.json présent, ne passez pas de noms de fichiers. npx tsc src/index.ts échoue avec error TS5112: tsconfig.json is present but will not be loaded if files are specified on commandline. Lancez simplement npx tsc, ou ajoutez --ignoreConfig si vous voulez vraiment compiler un seul fichier avec les réglages par défaut.

Mode watch

--watch (forme courte -w) garde le compilateur actif et recompile à chaque modification d'un fichier :

npx tsc --watch

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

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

Laissez-le ouvert dans un terminal à côté de votre éditeur. Arrêtez-le avec Ctrl+C.

Installer une version précise de TypeScript

Ajoutez la version après @ :

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 est la dernière version dont le compilateur est écrit en JavaScript. Certains outils qui appellent l'API JavaScript du compilateur en ont encore besoin, ce que la page TypeScript 7 aborde, avec la procédure de mise à jour.

Configurer l'éditeur

VS Code intègre le support de TypeScript : ouvrez un fichier .ts et vous obtenez le soulignement des erreurs, l'autocomplétion, les types au survol et le renommage sans rien installer. Pour profiter de la vitesse de TypeScript 7 dans l'éditeur, l'équipe TypeScript publie une extension dédiée qui fait passer VS Code au serveur de langage natif de TypeScript 7. WebStorm et les autres IDE JetBrains prennent en charge TypeScript d'emblée, et Neovim, Vim, Emacs, Zed et Sublime Text utilisent un serveur de langage TypeScript via leur support LSP.

Erreurs d'installation fréquentes

This is not the tsc command you are looking for. Vous avez lancé npx tsc dans un dossier sans TypeScript installé, et npx a récupéré un paquet obsolète qui s'appelle justement tsc. Installez le vrai avec npm install --save-dev typescript.

tsc: command not found, ou 'tsc' is not recognized as an internal or external command sous Windows. TypeScript n'est pas installé globalement, ou le dossier global de npm n'est pas dans votre PATH. Utilisez npx tsc dans un projet avec une installation locale, ou installez-le globalement et ouvrez un nouveau terminal.

error TS2591: Cannot find name 'process' (ou require ; __dirname donne TS2304). Les types des API de Node.js se trouvent dans un paquet séparé. Installez-le avec npm install --save-dev @types/node, puis ajoutez "types": ["node"] à compilerOptions : TypeScript 7 ne charge plus automatiquement tous les paquets @types installés.

error TS5011: The common source directory of 'tsconfig.json' is './src'. Vos fichiers sont dans src et vous avez réglé outDir mais pas rootDir. Ajoutez "rootDir": "./src".

error TS1295: ECMAScript imports and exports cannot be written in a CommonJS file under 'verbatimModuleSyntax'. npm init -y écrit "type": "commonjs" dans package.json, si bien que la configuration de tsc --init ("module": "nodenext" avec verbatimModuleSyntax) traite chaque fichier .ts comme du CommonJS, où import et export sont interdits. Passez à "type": "module", et écrivez les imports relatifs avec une extension .js : import { add } from "./math.js".